* 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
stored in the symbol's @code{variable-documentation} property. The
Emacs help functions (@pxref{Documentation}) look for this property.
-If the first character of @var{doc-string} is @samp{*}, it means that
-this variable is considered a user option. This lets users set the
-variable conveniently using the commands @code{set-variable} and
-@code{edit-options}. However, it is better to use @code{defcustom}
-instead of @code{defvar} for user option variables, so you can specify
-customization information. @xref{Customization}.
+If the variable is a user option that users would want to set
+interactively, you should use @samp{*} as the first character of
+@var{doc-string}. This lets users set the variable conveniently using
+the @code{set-variable} command. Note that you should nearly always
+use @code{defcustom} instead of @code{defvar} to define these
+variables, so that users can use @kbd{M-x customize} and related
+commands to set them. @xref{Customization}.
Here are some examples. This form defines @code{foo} but does not
initialize it:
@item @dots{}-form
The value is a form (an expression).
-@item @dots{}-functions
+@item @dots{}-forms
The value is a list of forms (expressions).
@item @dots{}-predicate
The value specifies options for a command.
@end table
- When you define a variable, always cvonsider whether you should mark
+ When you define a variable, always consider whether you should mark
it as ``risky''; see @ref{File Local Variables}.
When defining and initializing a variable that holds a complicated
@var{docstring})
(unless my-mode-map
(let ((map (make-sparse-keymap)))
- (define-key my-mode-map "\C-c\C-a" 'my-command)
+ (define-key map "\C-c\C-a" 'my-command)
@dots{}
(setq my-mode-map map)))
@end example
with @code{setq-default}.
@strong{Warning:} When a variable has buffer-local values in one or
-more buffers, you can get Emacs very confused by binding the variable
-with @code{let}, changing to a different current buffer in which a
-different binding is in effect, and then exiting the @code{let}. This
-can scramble the values of the buffer-local and default bindings.
+more buffers, binding the variable with @code{let} and changing to a
+different current buffer in which a different binding is in
+effect, and then exiting the @code{let}, the variable may not be
+restored to the value it had before the @code{let}.
To preserve your sanity, avoid using a variable in that way. If you
use @code{save-excursion} around each piece of code that changes to a
@example
@group
-(setq foo 'b)
+(setq foo 'g)
(set-buffer "a")
(make-local-variable 'foo)
@end group
(setq foo 'a)
(let ((foo 'temp))
+ ;; foo @result{} 'temp ; @r{let binding in buffer @samp{a}}
(set-buffer "b")
+ ;; foo @result{} 'g ; @r{the global value since foo is not local in @samp{b}}
@var{body}@dots{})
@group
-foo @result{} 'a ; @r{The old buffer-local value from buffer @samp{a}}
- ; @r{is now the default value.}
+foo @result{} 'a ; @r{we are still in buffer @samp{b}, but exiting the let}
+ ; @r{restored the local value in buffer @samp{a}}
@end group
@group
-(set-buffer "a")
-foo @result{} 'temp ; @r{The local @code{let} value that should be gone}
- ; @r{is now the buffer-local value in buffer @samp{a}.}
+(set-buffer "a") ; @r{This can be seen here:}
+foo @result{} 'a ; @r{we are back to the local value in buffer @samp{a}}
@end group
@end example
Displays}.
@strong{Note:} Do not use @code{make-local-variable} for a hook
-variable. Instead, use @code{make-local-hook}. @xref{Hooks}.
+variable. The hook variables are automatically made buffer-local
+as needed if you use the @var{local} argument to @code{add-hook} or
+@code{remove-hook}.
@end deffn
@deffn Command make-variable-buffer-local variable
list does @emph{not} change the buffer-local values of the variables.
@end defun
+@defun buffer-local-value variable buffer
+This function returns the buffer-local binding of @var{variable} (a
+symbol) in buffer @var{buffer}. If @var{variable} does not have a
+buffer-local binding in buffer @var{buffer}, it returns the default
+value (@pxref{Default Value}) of @var{variable} instead.
+@end defun
+
@deffn Command kill-local-variable variable
This function deletes the buffer-local binding (if any) for
@var{variable} (a symbol) in the current buffer. As a result, the
of frames---for example, all color frames, or all frames with dark
backgrounds. We have not implemented them because it is not clear that
this feature is really useful. You can get more or less the same
-results by adding a function to @code{after-make-frame-hook}, set up to
+results by adding a function to @code{after-make-frame-functions}, set up to
define a particular frame parameter according to the appropriate
conditions for each frame.
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}.
+
+@defun defvaralias alias-var base-var [docstring]
+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}.
+
+If the @var{docstring} argument is present, it specifies the documentation for
+@var{alias-var}; otherwise, it has the same documentation as @var{base-var},
+if any.
+@end defun
+
+@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
HCoop / bpt / emacs.git / blobdiff