@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/variables
@node Variables, Functions, Control Structures, Top
* Local Variables:: Variable values that exist only temporarily.
* Void Variables:: Symbols that lack values.
* Defining Variables:: A definition says a symbol is used as a variable.
-* Tips for Defining:: How to avoid bad results from quitting
- within the code to initialize a variable.
+* Tips for Defining:: Things you should think about when you
+ define a variable.
* Accessing Variables:: Examining values of variables whose names
are known only at run time.
* Setting Variables:: Storing new values in variables.
* 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
@node Global Variables
@end example
@node Constant Variables
-@section Variables That Never Change
+@section Variables that Never Change
@vindex nil
@vindex t
@kindex setting-constant
+@cindex keyword symbol
In Emacs Lisp, certain symbols normally evaluate to themselves. These
include @code{nil} and @code{t}, as well as any symbol whose name starts
-with @samp{:}. These symbols cannot be rebound, nor can their values be
-changed. Any attempt to set or bind @code{nil} or @code{t} signals a
-@code{setting-constant} error. The same is true for a symbol whose name
-starts with @samp{:}, except that you are allowed to set such a symbol to
-itself.
+with @samp{:} (these are called @dfn{keywords}). These symbols cannot
+be rebound, nor can their values be changed. Any attempt to set or bind
+@code{nil} or @code{t} signals a @code{setting-constant} error. The
+same is true for a keyword (a symbol whose name starts with @samp{:}),
+if it is interned in the standard obarray, except that setting such a
+symbol to itself is not an error.
@example
@group
@end group
@end example
-@defvar keyword-symbols-constant-flag
-@tindex keyword-symbols-constant-flag
-If this variable is @code{nil}, you are allowed to set and bind symbols
-whose names start with @samp{:} as you wish. This is to make it
-possible to run old Lisp programs which do that.
-@end defvar
+@defun keywordp object
+@tindex keywordp
+function returns @code{t} if @var{object} is a symbol whose name
+starts with @samp{:}, interned in the standard obarray, and returns
+@code{nil} otherwise.
+@end defun
@node Local Variables
@section Local Variables
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:
@code{nil} otherwise. (Variables other than user options exist for the
internal purposes of Lisp programs, and users need not know about them.)
-User option variables are distinguished from other variables by the
-first character of the @code{variable-documentation} property. If the
-property exists and is a string, and its first character is @samp{*},
-then the variable is a user option.
+User option variables are distinguished from other variables either
+though being declared using @code{defcustom}@footnote{They may also be
+declared equivalently in @file{cus-start.el}.} or by the first character
+of their @code{variable-documentation} property. If the property exists
+and is a string, and its first character is @samp{*}, then the variable
+is a user option.
@end defun
@kindex variable-interactive
If a user option variable has a @code{variable-interactive} property,
the @code{set-variable} command uses that value to control reading the
new value for the variable. The property's value is used as if it were
-to @code{interactive} (@pxref{Using Interactive}). However, this feature
-is largely obsoleted by @code{defcustom} (@pxref{Customization}).
+specified in @code{interactive} (@pxref{Using Interactive}). However,
+this feature is largely obsoleted by @code{defcustom}
+(@pxref{Customization}).
@strong{Warning:} If the @code{defconst} and @code{defvar} special
forms are used while the variable has a local binding, they set the
local binding's value; the global binding is not changed. This is not
-what we really want. To prevent it, use these special forms at top
+what you usually want. To prevent it, use these special forms at top
level in a file, where normally no local binding is in effect, and make
sure to load the file before making a local binding for the variable.
@node Tips for Defining
@section Tips for Defining Variables Robustly
+ When you define a variable whose value is a function, or a list of
+functions, use a name that ends in @samp{-function} or
+@samp{-functions}, respectively.
+
+ There are several other variable name conventions;
+here is a complete list:
+
+@table @samp
+@item @dots{}-hook
+The variable is a normal hook (@pxref{Hooks}).
+
+@item @dots{}-function
+The value is a function.
+
+@item @dots{}-functions
+The value is a list of functions.
+
+@item @dots{}-form
+The value is a form (an expression).
+
+@item @dots{}-forms
+The value is a list of forms (expressions).
+
+@item @dots{}-predicate
+The value is a predicate---a function of one argument that returns
+non-@code{nil} for ``good'' arguments and @code{nil} for ``bad''
+arguments.
+
+@item @dots{}-flag
+The value is significant only as to whether it is @code{nil} or not.
+
+@item @dots{}-program
+The value is a program name.
+
+@item @dots{}-command
+The value is a whole shell command.
+
+@item @samp{}-switches
+The value specifies options for a command.
+@end table
+
+ 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
value (such as a keymap with bindings in it), it's best to put the
entire computation of the value into the @code{defvar}, like this:
@example
(defvar my-mode-map nil
@var{docstring})
-(if my-mode-map
- nil
+(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
@example
(defvar my-mode-map nil
@var{docstring})
-(if my-mode-map
- nil
+(unless my-mode-map
(setq my-mode-map (make-sparse-keymap))
(define-key my-mode-map "\C-c\C-a" 'my-command)
@dots{})
@cindex dynamic scoping
Local bindings in Emacs Lisp have @dfn{indefinite scope} and
@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in
-the source code the binding can be accessed. Indefinite scope means
+the source code the binding can be accessed. ``Indefinite scope'' means
that any part of the program can potentially access the variable
binding. @dfn{Extent} refers to @emph{when}, as the program is
-executing, the binding exists. Dynamic extent means that the binding
+executing, the binding exists. ``Dynamic extent'' means that the binding
lasts as long as the activation of the construct that established it.
The combination of dynamic extent and indefinite scope is called
In a lexically scoped language, the binding of @code{x} in
@code{binder} would never be accessible in @code{user}, because
@code{user} is not textually contained within the function
-@code{binder}. However, in dynamically scoped Emacs Lisp, @code{user}
+@code{binder}. However, in dynamically-scoped Emacs Lisp, @code{user}
may or may not refer to the binding of @code{x} established in
-@code{binder}, depending on circumstances:
+@code{binder}, depending on the circumstances:
@itemize @bullet
@item
@cindex buffer-local variables
Global and local variable bindings are found in most programming
-languages in one form or another. Emacs also supports additional,
+languages in one form or another. Emacs, however, also supports additional,
unusual kinds of variable binding: @dfn{buffer-local} bindings, which
-apply only in one buffer, and frame-local bindings, which apply only in
+apply only in one buffer, and @dfn{frame-local} bindings, which apply only in
one frame. Having different values for a variable in different buffers
and/or frames is an important customization method.
A variable can have buffer-local bindings in some buffers but not in
other buffers. The default binding is shared by all the buffers that
don't have their own bindings for the variable. (This includes all
-newly created buffers.) If you set the variable in a buffer that does
+newly-created buffers.) If you set the variable in a buffer that does
not have a buffer-local binding for it, this sets the default binding
(assuming there are no frame-local bindings to complicate the matter),
so the new value is visible in all the buffers that see the default
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
variables cannot have buffer-local bindings as well. @xref{Multiple
Displays}.
-@strong{Note:} do not use @code{make-local-variable} for a hook
-variable. Instead, use @code{make-local-hook}. @xref{Hooks}.
+@strong{Note:} Do not use @code{make-local-variable} for a hook
+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
+
+ This section describes the functions and variables that affect
+processing of local variables lists in files.
+
+@defopt enable-local-variables
+This variable controls whether to process file local variables lists. A
+value of @code{t} means process the local variables lists
+unconditionally; @code{nil} means ignore them; anything else means ask
+the user what to do for each file. The default value is @code{t}.
+@end defopt
+
+@defun hack-local-variables &optional force
+This function parses, and binds or evaluates as appropriate, any local
+variables specified by the contents of the current buffer. The variable
+@code{enable-local-variables} has its effect here.
+
+The argument @var{force} usually comes from the argument @var{find-file}
+given to @code{normal-mode}.
+@end defun
+
+ If a file local variable list could specify the a function that will
+be called later, or an expression that will be executed later, simply
+visiting a file could take over your Emacs. To prevent this, Emacs
+takes care not to allow local variable lists to set such variables.
+
+ For one thing, any variable whose name ends in @samp{-function},
+@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form},
+@samp{-forms}, @samp{-program}, @samp{-command} or @samp{-predicate}
+cannot be set in a local variable list. In general, you should use such
+a name whenever it is appropriate for the variable's meaning.
+
+ In addition, any variable whose name has a non-@code{nil}
+@code{risky-local-variable} property is also ignored. So are
+all variables listed in @code{ignored-local-variables}:
+
+@defvar ignored-local-variables
+This variable holds a list of variables that should not be
+set by a file's local variables list. Any value specified
+for one of these variables is ignored.
+@end defvar
+
+ The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs
+normally asks for confirmation before handling it.
+@defopt enable-local-eval
+This variable controls processing of @samp{Eval:} in local variables
+lists in files being visited. A value of @code{t} means process them
+unconditionally; @code{nil} means ignore them; anything else means ask
+the user what to do for each file. The default value is @code{maybe}.
+@end defopt
HCoop / bpt / emacs.git / blobdiff