From: Gerd Moellmann <gerd@gnu.org>
Date: Fri, 5 Oct 2001 09:38:43 +0000 (+0000)
Subject: (Variable Aliases): New node.
X-Git-Tag: ttn-vms-21-2-B4~19746
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=26236f6d9c903a219fb1a1000f7fce17cc2bf5c3;p=emacs.git

(Variable Aliases): New node.
---

diff --git a/lispref/variables.texi b/lispref/variables.texi
index 5b981013708..097961e98bd 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -41,6 +41,7 @@ variable.
 * Buffer-Local Variables::  Variable values in effect only in one buffer.
 * Frame-Local Variables::   Variable values in effect only in one frame.
 * Future Local Variables::  New kinds of local values we might add some day.
+* Variable Aliases::      Variables that are aliases for other variables.
 * File Local Variables::  Handling local variable lists in files.
 @end menu
 
@@ -1654,6 +1655,48 @@ bindings offer a way to handle these situations more robustly.
   If sufficient application is found for either of these two kinds of
 local bindings, we will provide it in a subsequent Emacs version.
 
+@node Variable Aliases
+@section Variable Aliases
+
+  It is sometimes useful to make two variables synonyms, so that both
+variables always have the same value, and changing either one also
+changes the other.  Whenever you change the name of a
+variable---either because you realize its old name was not well
+chosen, or because its meaning has partly changed---it can be useful
+to keep the old name as an @emph{alias} of the new one for
+compatibility.  You can do this with @code{defvaralias}.
+
+@defmacro defvaralias alias-var base-var
+This function defines the symbol @var{alias-var} as a variable alias
+for symbol @var{base-var}.  This means that retrieving the value of
+@var{alias-var} returns the value of @var{base-var}, and changing the
+value of @var{alias-var} changes the value of @var{base-var}.
+@end defmacro
+
+@defun indirect-variable variable
+This function returns the variable at the end of the chain of aliases
+of @var{variable}.  If @var{variable} is not a symbol, or if @var{variable} is
+not defined as an alias, the function returns @var{variable}.
+@end defun
+
+@example
+(defvaralias 'foo 'bar)
+(indirect-variable 'foo)
+     @result{} bar
+(indirect-variable 'bar)
+     @result{} bar
+(setq bar 2)
+bar
+     @result{} 2
+foo
+     @result{} 2
+(setq foo 0)
+bar
+     @result{} 0
+foo
+     @result{} 0
+@end example
+
 @node File Local Variables
 @section File Local Variables