@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 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:: 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.
* Variable Scoping:: How Lisp chooses among local and global values.
* 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
@noindent
assuming the @code{setq} form shown above has already been executed.
- If you do another @code{setq}, the new value replaces the old one:
+ If you do set the same variable again, the new value replaces the old
+one:
@example
@group
@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
- Emacs Lisp has two special symbols, @code{nil} and @code{t}, that
-always evaluate to themselves. These symbols cannot be rebound, nor can
-their value cells be changed. An attempt to change the value of
-@code{nil} or @code{t} signals a @code{setting-constant} error.
+ 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 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
+@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
@cindex binding local variables
Global variables have values that last until explicitly superseded
with new values. Sometimes it is useful to create variable values that
-exist temporarily---only while within a certain part of the program.
+exist temporarily---only until a certain part of the program finishes.
These values are called @dfn{local}, and the variables so used are
called @dfn{local variables}.
If you set a variable (such as with @code{setq}) while it is local,
this replaces the local value; it does not alter the global value, or
-previous local values that are shadowed. To model this behavior, we
+previous local values, that are shadowed. To model this behavior, we
speak of a @dfn{local binding} of the variable as well as a local value.
The local binding is a conceptual place that holds a local value.
A variable can have more than one local binding at a time (for
example, if there are nested @code{let} forms that bind it). In such a
case, the most recently created local binding that still exists is the
-@dfn{current binding} of the variable. (This is called @dfn{dynamic
-scoping}; see @ref{Variable Scoping}.) If there are no local bindings,
-the variable's global binding is its current binding. We also call the
-current binding the @dfn{most-local existing binding}, for emphasis.
-Ordinary evaluation of a symbol always returns the value of its current
-binding.
+@dfn{current binding} of the variable. (This rule is called
+@dfn{dynamic scoping}; see @ref{Variable Scoping}.) If there are no
+local bindings, the variable's global binding is its current binding.
+We sometimes call the current binding the @dfn{most-local existing
+binding}, for emphasis. Ordinary evaluation of a symbol always returns
+the value of its current binding.
The special forms @code{let} and @code{let*} exist to create
local bindings.
is omitted, @code{nil} is used.
All of the @var{value-form}s in @var{bindings} are evaluated in the
-order they appear and @emph{before} any of the symbols are bound. Here
-is an example of this: @code{Z} is bound to the old value of @code{Y},
-which is 2, not the new value, 1.
+order they appear and @emph{before} binding any of the symbols to them.
+Here is an example of this: @code{Z} is bound to the old value of
+@code{Y}, which is 2, not the new value of @code{Y}, which is 1.
@example
@group
@code{condition-case} (@pxref{Errors}).
@end itemize
+ Variables can also have buffer-local bindings (@pxref{Buffer-Local
+Variables}) and frame-local bindings (@pxref{Frame-Local Variables}); a
+few variables have terminal-local bindings (@pxref{Multiple Displays}).
+These kinds of bindings work somewhat like ordinary local bindings, but
+they are localized depending on ``where'' you are in Emacs, rather than
+localized in time.
+
@defvar max-specpdl-size
@cindex variable limit error
@cindex evaluation error
@cindex infinite recursion
- This variable defines the limit on the total number of local variable
+This variable defines the limit on the total number of local variable
bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits})
that are allowed before signaling an error (with data @code{"Variable
binding depth exceeds max-specpdl-size"}).
- This limit, with the associated error when it is exceeded, is one way
+This limit, with the associated error when it is exceeded, is one way
that Lisp avoids infinite recursion on an ill-defined function.
-
- The default value is 600.
-
- @code{max-lisp-eval-depth} provides another limit on depth of nesting.
+@code{max-lisp-eval-depth} provides another limit on depth of nesting.
@xref{Eval}.
+
+The default value is 600. Entry to the Lisp debugger increases the
+value, if there is little room left, to make sure the debugger itself
+has room to execute.
@end defvar
@node Void Variables
using @code{makunbound}.
@defun makunbound symbol
-This function makes the current binding of @var{symbol} void.
+This function makes the current variable binding of @var{symbol} void.
Subsequent attempts to use this symbol's value as a variable will signal
-the error @code{void-variable}, unless or until you set it again.
+the error @code{void-variable}, unless and until you set it again.
@code{makunbound} returns @var{symbol}.
@example
@group
-(makunbound 'x) ; @r{Make the global value}
- ; @r{of @code{x} void.}
+(makunbound 'x) ; @r{Make the global value of @code{x} void.}
@result{} x
@end group
@group
local binding, since all the constructs that create local bindings
create them with values. In this case, the voidness lasts at most as
long as the binding does; when the binding is removed due to exit from
-the construct that made it, the previous or global binding is reexposed
-as usual, and the variable is no longer void unless the newly reexposed
-binding was void all along.
+the construct that made it, the previous local or global binding is
+reexposed as usual, and the variable is no longer void unless the newly
+reexposed binding was void all along.
@smallexample
@group
variables in a program.
The difference between @code{defconst} and @code{defvar} is primarily
-a matter of intent, serving to inform human readers of whether programs
-will change the variable. Emacs Lisp does not restrict the ways in
-which a variable can be used based on @code{defconst} or @code{defvar}
+a matter of intent, serving to inform human readers of whether the value
+should ever change. Emacs Lisp does not restrict the ways in which a
+variable can be used based on @code{defconst} or @code{defvar}
declarations. However, it does make a difference for initialization:
@code{defconst} unconditionally initializes the variable, while
@code{defvar} initializes it only if it is void.
+@ignore
One would expect user option variables to be defined with
@code{defconst}, since programs do not change them. Unfortunately, this
has bad results if the definition is in a library that is not preloaded:
loaded. Users would like to be able to set user options in their init
files, and override the default values given in the definitions. For
this reason, user options must be defined with @code{defvar}.
+@end ignore
@defspec defvar symbol [value [doc-string]]
-This special form defines @var{symbol} as a value and initializes it.
-The definition informs a person reading your code that @var{symbol} is
-used as a variable that programs are likely to set or change. It is
-also used for all user option variables except in the preloaded parts of
-Emacs. Note that @var{symbol} is not evaluated; the symbol to be
+This special form defines @var{symbol} as a variable and can also
+initialize and document it. The definition informs a person reading
+your code that @var{symbol} is used as a variable that might be set or
+changed. Note that @var{symbol} is not evaluated; the symbol to be
defined must appear explicitly in the @code{defvar}.
-If @var{symbol} already has a value (i.e., it is not void), @var{value}
-is not even evaluated, and @var{symbol}'s value remains unchanged. If
-@var{symbol} is void and @var{value} is specified, @code{defvar}
-evaluates it and sets @var{symbol} to the result. (If @var{value} is
-omitted, the value of @var{symbol} is not changed in any case.)
+If @var{symbol} is void and @var{value} is specified, @code{defvar}
+evaluates it and sets @var{symbol} to the result. But if @var{symbol}
+already has a value (i.e., it is not void), @var{value} is not even
+evaluated, and @var{symbol}'s value remains unchanged. If @var{value}
+is omitted, the value of @var{symbol} is not changed in any case.
If @var{symbol} has a buffer-local binding in the current buffer,
-@code{defvar} sets the default value, not the local value.
-@xref{Buffer-Local Variables}.
+@code{defvar} operates on the default value, which is buffer-independent,
+not the current (buffer-local) binding. It sets the default value if
+the default value is void. @xref{Buffer-Local Variables}.
+
+When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
+Emacs Lisp mode (@code{eval-defun}), a special feature of
+@code{eval-defun} arranges to set the variable unconditionally, without
+testing whether its value is void.
If the @var{doc-string} argument appears, it specifies the documentation
for the variable. (This opportunity to specify documentation is one of
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 conventiently using the commands @code{set-variable} and
-@code{edit-options}.
+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}.
-For example, this form defines @code{foo} but does not set its value:
+Here are some examples. This form defines @code{foo} but does not
+initialize it:
@example
@group
@end group
@end example
-The following example sets the value of @code{bar} to @code{23}, and
-gives it a documentation string:
+This example initializes the value of @code{bar} to @code{23}, and gives
+it a documentation string:
@example
@group
The following form changes the documentation string for @code{bar},
making it a user option, but does not change the value, since @code{bar}
-already has a value. (The addition @code{(1+ 23)} is not even
-performed.)
+already has a value. (The addition @code{(1+ nil)} would get an error
+if it were evaluated, but since it is not evaluated, there is no error.)
@example
@group
-(defvar bar (1+ 23)
+(defvar bar (1+ nil)
"*The normal weight of a bar.")
@result{} bar
@end group
(progn
(if (not (boundp '@var{symbol}))
(setq @var{symbol} @var{value}))
- (put '@var{symbol} 'variable-documentation '@var{doc-string})
+ (if '@var{doc-string}
+ (put '@var{symbol} 'variable-documentation '@var{doc-string}))
'@var{symbol})
@end group
@end example
@defspec defconst symbol [value [doc-string]]
This special form defines @var{symbol} as a value and initializes it.
-It informs a person reading your code that @var{symbol} has a global
-value, established here, that will not normally be changed or locally
-bound by the execution of the program. The user, however, may be
-welcome to change it. Note that @var{symbol} is not evaluated; the
+It informs a person reading your code that @var{symbol} has a standard
+global value, established here, that should not be changed by the user
+or by other programs. Note that @var{symbol} is not evaluated; the
symbol to be defined must appear explicitly in the @code{defconst}.
-@code{defconst} always evaluates @var{value} and sets the global value
-of @var{symbol} to the result, provided @var{value} is given. If
-@var{symbol} has a buffer-local binding in the current buffer,
-@code{defconst} sets the default value, not the local value.
-
-@strong{Please note:} Don't use @code{defconst} for user option
-variables in libraries that are not standardly preloaded. The user
-should be able to specify a value for such a variable in the
-@file{.emacs} file, so that it will be in effect if and when the library
-is loaded later.
+@code{defconst} always evaluates @var{value}, and sets the value of
+@var{symbol} to the result if @var{value} is given. If @var{symbol}
+does have a buffer-local binding in the current buffer, @code{defconst}
+sets the default value, not the buffer-local value. (But you should not
+be making buffer-local bindings for a symbol that is defined with
+@code{defconst}.)
Here, @code{pi} is a constant that presumably ought not to be changed
by anyone (attempts by the Indiana State Legislature notwithstanding).
@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,
-@code{set-variable} uses that value to control reading the new value for
-the variable. The property's value is used as if it were the argument
-to @code{interactive}.
+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
+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
+ (let ((map (make-sparse-keymap)))
+ (define-key map "\C-c\C-a" 'my-command)
+ @dots{}
+ map)
+ @var{docstring})
+@end example
+
+@noindent
+This method has several benefits. First, if the user quits while
+loading the file, the variable is either still uninitialized or
+initialized properly, never in-between. If it is still uninitialized,
+reloading the file will initialize it properly. Second, reloading the
+file once the variable is initialized will not alter it; that is
+important if the user has run hooks to alter part of the contents (such
+as, to rebind keys). Third, evaluating the @code{defvar} form with
+@kbd{C-M-x} @emph{will} reinitialize the map completely.
+
+ Putting so much code in the @code{defvar} form has one disadvantage:
+it puts the documentation string far away from the line which names the
+variable. Here's a safe way to avoid that:
+
+@example
+(defvar my-mode-map nil
+ @var{docstring})
+(unless my-mode-map
+ (let ((map (make-sparse-keymap)))
+ (define-key map "\C-c\C-a" 'my-command)
+ @dots{}
+ (setq my-mode-map map)))
+@end example
+
+@noindent
+This has all the same advantages as putting the initialization inside
+the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on
+each form, if you do want to reinitialize the variable.
+
+ But be careful not to write the code like this:
+
+@example
+(defvar my-mode-map nil
+ @var{docstring})
+(unless my-mode-map
+ (setq my-mode-map (make-sparse-keymap))
+ (define-key my-mode-map "\C-c\C-a" 'my-command)
+ @dots{})
+@end example
+
+@noindent
+This code sets the variable, then alters it, but it does so in more than
+one step. If the user quits just after the @code{setq}, that leaves the
+variable neither correctly initialized nor void nor @code{nil}. Once
+that happens, reloading the file will not initialize the variable; it
+will remain incomplete.
+
@node Accessing Variables
@section Accessing Variable Values
@end group
@end example
-A @code{void-variable} error is signaled if @var{symbol} has neither a
-local binding nor a global value.
+A @code{void-variable} error is signaled if the current binding of
+@var{symbol} is void.
@end defun
@node Setting Variables
@cindex CL note---@code{set} local
@quotation
@b{Common Lisp note:} In Common Lisp, @code{set} always changes the
-symbol's special value, ignoring any lexical bindings. In Emacs Lisp,
-all variables and all bindings are (in effect) special, so @code{set}
+symbol's ``special'' or dynamic value, ignoring any lexical bindings.
+In Emacs Lisp, all variables and all bindings are dynamic, so @code{set}
always affects the most local existing binding.
@end quotation
@end defun
@defun add-to-list symbol element
This function sets the variable @var{symbol} by consing @var{element}
onto the old value, if @var{element} is not already a member of that
-value. The value of @var{symbol} had better be a list already.
+value. It returns the resulting list, whether updated or not. The
+value of @var{symbol} had better be a list already before the call.
+
+The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
+is an ordinary function, like @code{set} and unlike @code{setq}. Quote
+the argument yourself if that is what you want.
+@end defun
Here's a scenario showing how to use @code{add-to-list}:
foo ;; @r{@code{foo} was changed.}
@result{} (c a b)
@end example
-@end defun
An equivalent expression for @code{(add-to-list '@var{var}
@var{value})} is this:
@node Variable Scoping
@section Scoping Rules for Variable Bindings
- A given symbol @code{foo} may have several local variable bindings,
+ A given symbol @code{foo} can have several local variable bindings,
established at different places in the Lisp program, as well as a global
binding. The most recently established binding takes precedence over
the others.
@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
@cindex CL note---special variables
@quotation
-@b{Common Lisp note:} Variables declared ``special'' in Common Lisp
-are dynamically scoped, like variables in Emacs Lisp.
+@b{Common Lisp note:} Variables declared ``special'' in Common Lisp are
+dynamically scoped, like all variables in Emacs Lisp.
@end quotation
@menu
@end group
@group
-(defun user () ; @r{@code{x} is used in @code{user}.}
+(defun user () ; @r{@code{x} is used ``free'' in @code{user}.}
(list x))
@end group
@end example
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
@code{binder}.
@item
-If we define @code{foo} as follows and call @code{binder}, then the
+If we define @code{foo} as follows and then call @code{binder}, then the
binding made in @code{binder} will be seen in @code{user}:
@example
@end example
@item
-If we define @code{foo} as follows and call @code{binder}, then the
-binding made in @code{binder} @emph{will not} be seen in @code{user}:
+However, if we define @code{foo} as follows and then call @code{binder},
+then the binding made in @code{binder} @emph{will not} be seen in
+@code{user}:
@example
(defun foo (x)
by @code{foo} instead of the one bound by @code{binder}.
@end itemize
+Emacs Lisp uses dynamic scoping because simple implementations of
+lexical scoping are slow. In addition, every Lisp system needs to offer
+dynamic scoping at least as an option; if lexical scoping is the norm,
+there must be a way to specify dynamic scoping instead for a particular
+variable. It might not be a bad thing for Emacs to offer both, but
+implementing it with dynamic scoping only was much easier.
+
@node Extent
@subsection Extent
this, but Emacs Lisp does not.
To illustrate this, the function below, @code{make-add}, returns a
-function that purports to add @var{n} to its own argument @var{m}.
-This would work in Common Lisp, but it does not work as intended in
-Emacs Lisp, because after the call to @code{make-add} exits, the
-variable @code{n} is no longer bound to the actual argument 2.
+function that purports to add @var{n} to its own argument @var{m}. This
+would work in Common Lisp, but it does not do the job in Emacs Lisp,
+because after the call to @code{make-add} exits, the variable @code{n}
+is no longer bound to the actual argument 2.
@example
(defun make-add (n)
works) may help you understand dynamic binding. This technique is
called @dfn{deep binding} and was used in early Lisp systems.
- Suppose there is a stack of bindings: variable-value pairs. At entry
-to a function or to a @code{let} form, we can push bindings on the stack
-for the arguments or local variables created there. We can pop those
-bindings from the stack at exit from the binding construct.
+ Suppose there is a stack of bindings, which are variable-value pairs.
+At entry to a function or to a @code{let} form, we can push bindings
+onto the stack for the arguments or local variables created there. We
+can pop those bindings from the stack at exit from the binding
+construct.
We can find the value of a variable by searching the stack from top to
bottom for a binding for that variable; the value from that binding is
In shallow binding, setting the variable works by storing a value in
the value cell. Creating a new binding works by pushing the old value
-(belonging to a previous binding) on a stack, and storing the local value
-in the value cell. Eliminating a binding works by popping the old value
-off the stack, into the value cell.
+(belonging to a previous binding) onto a stack, and storing the new
+local value in the value cell. Eliminating a binding works by popping
+the old value off the stack, into the value cell.
We use shallow binding because it has the same results as deep
binding, but runs faster, since there is never a need to search for a
the effect will be.
@end itemize
+ In either case, you should define the variable with @code{defvar}.
+This helps other people understand your program by telling them to look
+for inter-function usage. It also avoids a warning from the byte
+compiler. Choose the variable's name to avoid name conflicts---don't
+use short names like @code{x}.
+
@node Buffer-Local Variables
@section Buffer-Local Variables
@cindex variables, buffer-local
@cindex buffer-local variables
Global and local variable bindings are found in most programming
-languages in one form or another. Emacs also supports another, unusual
-kind of variable binding: @dfn{buffer-local} bindings, which apply only
-to one buffer. Emacs Lisp is meant for programming editing commands,
-and having different values for a variable in different buffers is an
-important customization method. (A few variables have bindings that
-are local to a given X terminal; see @ref{Multiple Displays}.)
+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 @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.
+
+ This section describes buffer-local bindings; for frame-local
+bindings, see the following section, @ref{Frame-Local Variables}. (A few
+variables have bindings that are local to each terminal; see
+@ref{Multiple Displays}.)
@menu
* Intro to Buffer-Local:: Introduction and concepts.
* Creating Buffer-Local:: Creating and destroying buffer-local bindings.
* Default Value:: The default value is seen in buffers
- that don't have their own local values.
+ that don't have their own buffer-local values.
@end menu
@node Intro to Buffer-Local
particular buffer. The binding is in effect when that buffer is
current; otherwise, it is not in effect. If you set the variable while
a buffer-local binding is in effect, the new value goes in that binding,
-so the global binding is unchanged; this means that the change is
-visible in that buffer alone.
-
- A variable may have buffer-local bindings in some buffers but not in
-others. The global binding is shared by all the buffers that don't have
-their own bindings. Thus, if you set the variable in a buffer that does
-not have a buffer-local binding for it, the new value is visible in all
-buffers except those with buffer-local bindings. (Here we are assuming
-that there are no @code{let}-style local bindings to complicate the issue.)
+so its other bindings are unchanged. This means that the change is
+visible only in the buffer where you made it.
+
+ The variable's ordinary binding, which is not associated with any
+specific buffer, is called the @dfn{default binding}. In most cases,
+this is the global binding.
+
+ 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
+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
+binding.
The most common use of buffer-local bindings is for major modes to change
variables that control the behavior of commands. For example, C mode and
Lisp mode both set the variable @code{paragraph-start} to specify that only
blank lines separate paragraphs. They do this by making the variable
buffer-local in the buffer that is being put into C mode or Lisp mode, and
-then setting it to the new value for that mode.
+then setting it to the new value for that mode. @xref{Major Modes}.
The usual way to make a buffer-local binding is with
-@code{make-local-variable}, which is what major mode commands use. This
-affects just the current buffer; all other buffers (including those yet to
-be created) continue to share the global value.
+@code{make-local-variable}, which is what major mode commands typically
+use. This affects just the current buffer; all other buffers (including
+those yet to be created) will continue to share the default value unless
+they are explicitly given their own buffer-local bindings.
@cindex automatically buffer-local
A more powerful operation is to mark the variable as
variable local in all buffers, even those yet to be created. More
precisely, the effect is that setting the variable automatically makes
the variable local to the current buffer if it is not already so. All
-buffers start out by sharing the global value of the variable as usual,
-but any @code{setq} creates a buffer-local binding for the current
+buffers start out by sharing the default value of the variable as usual,
+but setting the variable creates a buffer-local binding for the current
buffer. The new value is stored in the buffer-local binding, leaving
-the (default) global binding untouched. The global value can no longer
-be changed with @code{setq}; you need to use @code{setq-default} to do
-that.
+the default binding untouched. This means that the default value cannot
+be changed with @code{setq} in any buffer; the only way to change it is
+with @code{setq-default}.
- @strong{Warning:} When a variable has 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 global and local bindings.
+ @strong{Warning:} When a variable has buffer-local values in one or
+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 that series of actions. If you use
-@code{save-excursion} around each piece of code that changes to a
-different current buffer, you will not have this problem. Here is an
-example of what to avoid:
+ 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
+different current buffer, you will not have this problem
+(@pxref{Excursions}). Here is an example of what to avoid:
@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")
- @dots{})
+ ;; 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 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
buffer-local binding of buffer @samp{b}.
When a file specifies local variable values, these become buffer-local
-values when you visit the file. @xref{Auto Major Mode}.
+values when you visit the file. @xref{File Variables,,, emacs, The
+GNU Emacs Manual}.
@node Creating Buffer-Local
@subsection Creating and Deleting Buffer-Local Bindings
@end example
Making a variable buffer-local within a @code{let}-binding for that
-variable does not work. This is because @code{let} does not distinguish
-between different kinds of bindings; it knows only which variable the
-binding was made for.
-
-@strong{Note:} do not use @code{make-local-variable} for a hook
-variable. Instead, use @code{make-local-hook}. @xref{Hooks}.
+variable does not work reliably, unless the buffer in which you do this
+is not current either on entry to or exit from the @code{let}. This is
+because @code{let} does not distinguish between different kinds of
+bindings; it knows only which variable the binding was made for.
+
+If the variable is terminal-local, this function signals an error. Such
+variables cannot have buffer-local bindings as well. @xref{Multiple
+Displays}.
+
+@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
buffer-local, so that any subsequent attempt to set it will make it
local to the current buffer at the time.
+A peculiar wrinkle of this feature is that binding the variable (with
+@code{let} or other binding constructs) does not create a buffer-local
+binding for it. Only setting the variable (with @code{set} or
+@code{setq}) does so.
+
The value returned is @var{variable}.
+
+@strong{Warning:} Don't assume that you should use
+@code{make-variable-buffer-local} for user-option variables, simply
+because users @emph{might} want to customize them differently in
+different buffers. Users can make any variable local, when they wish
+to. It is better to leave the choice to them.
+
+The time to use @code{make-variable-buffer-local} is when it is crucial
+that no two buffers ever share the same binding. For example, when a
+variable is used for internal purposes in a Lisp program which depends
+on having separate values in separate buffers, then using
+@code{make-variable-buffer-local} can be the best solution.
@end deffn
+@defun local-variable-p variable &optional buffer
+This returns @code{t} if @var{variable} is buffer-local in buffer
+@var{buffer} (which defaults to the current buffer); otherwise,
+@code{nil}.
+@end defun
+
@defun buffer-local-variables &optional buffer
This function returns a list describing the buffer-local variables in
-buffer @var{buffer}. It returns an association list (@pxref{Association
-Lists}) in which each association contains one buffer-local variable and
-its value. When a buffer-local variable is void in @var{buffer}, then
-it appears directly in the resulting list. If @var{buffer} is omitted,
-the current buffer is used.
+buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is
+used.) It returns an association list (@pxref{Association Lists}) in
+which each element contains one buffer-local variable and its value.
+However, when a variable's buffer-local binding in @var{buffer} is void,
+then the variable appears directly in the resulting list.
@example
@group
(setq lcl (buffer-local-variables))
;; @r{First, built-in variables local in all buffers:}
@result{} ((mark-active . nil)
- (buffer-undo-list nil)
+ (buffer-undo-list . nil)
(mode-name . "Fundamental")
@dots{}
@group
- ;; @r{Next, non-built-in local variables.}
- ;; @r{This one is local and void:}
+ ;; @r{Next, non-built-in buffer-local variables.}
+ ;; @r{This one is buffer-local and void:}
foobar
- ;; @r{This one is local and nonvoid:}
+ ;; @r{This one is buffer-local and nonvoid:}
(bind-me . 69))
@end group
@end example
Note that storing new values into the @sc{cdr}s of cons cells in this
-list does @emph{not} change the local values of the variables.
+list does @emph{not} change the buffer-local values of the variables.
@end defun
-@defun local-variable-p variable
-This returns @code{t} if @var{variable} is buffer-local in the current
-buffer. It is much faster to get the answer this way than to examine
-the value of @code{buffer-local-variables}.
+@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
-global (default) binding of @var{variable} becomes visible in this
-buffer. Usually this results in a change in the value of
-@var{variable}, since the global value is usually different from the
-buffer-local value just eliminated.
+default binding of @var{variable} becomes visible in this buffer. This
+typically results in a change in the value of @var{variable}, since the
+default value is usually different from the buffer-local value just
+eliminated.
-If you kill the local binding of a variable that automatically becomes
-local when set, this makes the global value visible in the current
-buffer. However, if you set the variable again, that will once again
-create a local binding for it.
+If you kill the buffer-local binding of a variable that automatically
+becomes buffer-local when set, this makes the default value visible in
+the current buffer. However, if you set the variable again, that will
+once again create a buffer-local binding for it.
@code{kill-local-variable} returns @var{variable}.
This function also resets certain other information pertaining to the
buffer: it sets the local keymap to @code{nil}, the syntax table to the
-value of @code{standard-syntax-table}, and the abbrev table to the value
-of @code{fundamental-mode-abbrev-table}.
+value of @code{(standard-syntax-table)}, the case table to
+@code{(standard-case-table)}, and the abbrev table to the value of
+@code{fundamental-mode-abbrev-table}.
+
+The very first thing this function does is run the normal hook
+@code{change-major-mode-hook} (see below).
Every major mode command begins by calling this function, which has the
effect of switching to Fundamental mode and erasing most of the effects
@code{kill-all-local-variables} returns @code{nil}.
@end defun
+@defvar change-major-mode-hook
+The function @code{kill-all-local-variables} runs this normal hook
+before it does anything else. This gives major modes a way to arrange
+for something special to be done if the user switches to a different
+major mode. For best results, make this variable buffer-local, so that
+it will disappear after doing its job and will not interfere with the
+subsequent major mode. @xref{Hooks}.
+@end defvar
+
@c Emacs 19 feature
@cindex permanent local variable
-A local variable is @dfn{permanent} if the variable name (a symbol) has a
-@code{permanent-local} property that is non-@code{nil}. Permanent
-locals are appropriate for data pertaining to where the file came from
-or how to save it, rather than with how to edit the contents.
+A buffer-local variable is @dfn{permanent} if the variable name (a
+symbol) has a @code{permanent-local} property that is non-@code{nil}.
+Permanent locals are appropriate for data pertaining to where the file
+came from or how to save it, rather than with how to edit the contents.
@node Default Value
@subsection The Default Value of a Buffer-Local Variable
The global value of a variable with buffer-local bindings is also
called the @dfn{default} value, because it is the value that is in
-effect except when specifically overridden.
+effect whenever neither the current buffer nor the selected frame has
+its own binding for the variable.
The functions @code{default-value} and @code{setq-default} access and
change a variable's default value regardless of whether the current
@c Emacs 19 feature
The special forms @code{defvar} and @code{defconst} also set the
-default value (if they set the variable at all), rather than any local
-value.
+default value (if they set the variable at all), rather than any
+buffer-local or frame-local value.
@defun default-value symbol
This function returns @var{symbol}'s default value. This is the value
-that is seen in buffers that do not have their own values for this
-variable. If @var{symbol} is not buffer-local, this is equivalent to
-@code{symbol-value} (@pxref{Accessing Variables}).
+that is seen in buffers and frames that do not have their own values for
+this variable. If @var{symbol} is not buffer-local, this is equivalent
+to @code{symbol-value} (@pxref{Accessing Variables}).
@end defun
@c Emacs 19 feature
@code{symbol-value}.
@end defun
-@defspec setq-default symbol value
-This sets the default value of @var{symbol} to @var{value}. It does not
-evaluate @var{symbol}, but does evaluate @var{value}. The value of the
-@code{setq-default} form is @var{value}.
+@defspec setq-default [symbol form]@dots{}
+This special form gives each @var{symbol} a new default value, which is
+the result of evaluating the corresponding @var{form}. It does not
+evaluate @var{symbol}, but does evaluate @var{form}. The value of the
+@code{setq-default} form is the value of the last @var{form}.
If a @var{symbol} is not buffer-local for the current buffer, and is not
marked automatically buffer-local, @code{setq-default} has the same
@example
@group
;; @r{In buffer @samp{foo}:}
-(make-local-variable 'local)
- @result{} local
+(make-local-variable 'buffer-local)
+ @result{} buffer-local
@end group
@group
-(setq local 'value-in-foo)
+(setq buffer-local 'value-in-foo)
@result{} value-in-foo
@end group
@group
-(setq-default local 'new-default)
+(setq-default buffer-local 'new-default)
@result{} new-default
@end group
@group
-local
+buffer-local
@result{} value-in-foo
@end group
@group
-(default-value 'local)
+(default-value 'buffer-local)
@result{} new-default
@end group
@group
;; @r{In (the new) buffer @samp{bar}:}
-local
+buffer-local
@result{} new-default
@end group
@group
-(default-value 'local)
+(default-value 'buffer-local)
@result{} new-default
@end group
@group
-(setq local 'another-default)
+(setq buffer-local 'another-default)
@result{} another-default
@end group
@group
-(default-value 'local)
+(default-value 'buffer-local)
@result{} another-default
@end group
@group
;; @r{Back in buffer @samp{foo}:}
-local
+buffer-local
@result{} value-in-foo
-(default-value 'local)
+(default-value 'buffer-local)
@result{} another-default
@end group
@end example
@defun set-default symbol value
This function is like @code{setq-default}, except that @var{symbol} is
-evaluated.
+an ordinary evaluated argument.
@example
@group
@end group
@end example
@end defun
+
+@node Frame-Local Variables
+@section Frame-Local Variables
+
+ Just as variables can have buffer-local bindings, they can also have
+frame-local bindings. These bindings belong to one frame, and are in
+effect when that frame is selected. Frame-local bindings are actually
+frame parameters: you create a frame-local binding in a specific frame
+by calling @code{modify-frame-parameters} and specifying the variable
+name as the parameter name.
+
+ To enable frame-local bindings for a certain variable, call the function
+@code{make-variable-frame-local}.
+
+@deffn Command make-variable-frame-local variable
+Enable the use of frame-local bindings for @var{variable}. This does
+not in itself create any frame-local bindings for the variable; however,
+if some frame already has a value for @var{variable} as a frame
+parameter, that value automatically becomes a frame-local binding.
+
+If the variable is terminal-local, this function signals an error,
+because such variables cannot have frame-local bindings as well.
+@xref{Multiple Displays}. A few variables that are implemented
+specially in Emacs can be (and usually are) buffer-local, but can never
+be frame-local.
+@end deffn
+
+ Buffer-local bindings take precedence over frame-local bindings. Thus,
+consider a variable @code{foo}: if the current buffer has a buffer-local
+binding for @code{foo}, that binding is active; otherwise, if the
+selected frame has a frame-local binding for @code{foo}, that binding is
+active; otherwise, the default binding of @code{foo} is active.
+
+ Here is an example. First we prepare a few bindings for @code{foo}:
+
+@example
+(setq f1 (selected-frame))
+(make-variable-frame-local 'foo)
+
+;; @r{Make a buffer-local binding for @code{foo} in @samp{b1}.}
+(set-buffer (get-buffer-create "b1"))
+(make-local-variable 'foo)
+(setq foo '(b 1))
+
+;; @r{Make a frame-local binding for @code{foo} in a new frame.}
+;; @r{Store that frame in @code{f2}.}
+(setq f2 (make-frame))
+(modify-frame-parameters f2 '((foo . (f 2))))
+@end example
+
+ Now we examine @code{foo} in various contexts. Whenever the
+buffer @samp{b1} is current, its buffer-local binding is in effect,
+regardless of the selected frame:
+
+@example
+(select-frame f1)
+(set-buffer (get-buffer-create "b1"))
+foo
+ @result{} (b 1)
+
+(select-frame f2)
+(set-buffer (get-buffer-create "b1"))
+foo
+ @result{} (b 1)
+@end example
+
+@noindent
+Otherwise, the frame gets a chance to provide the binding; when frame
+@code{f2} is selected, its frame-local binding is in effect:
+
+@example
+(select-frame f2)
+(set-buffer (get-buffer "*scratch*"))
+foo
+ @result{} (f 2)
+@end example
+
+@noindent
+When neither the current buffer nor the selected frame provides
+a binding, the default binding is used:
+
+@example
+(select-frame f1)
+(set-buffer (get-buffer "*scratch*"))
+foo
+ @result{} nil
+@end example
+
+@noindent
+When the active binding of a variable is a frame-local binding, setting
+the variable changes that binding. You can observe the result with
+@code{frame-parameters}:
+
+@example
+(select-frame f2)
+(set-buffer (get-buffer "*scratch*"))
+(setq foo 'nobody)
+(assq 'foo (frame-parameters f2))
+ @result{} (foo . nobody)
+@end example
+
+@node Future Local Variables
+@section Possible Future Local Variables
+
+ We have considered the idea of bindings that are local to a category
+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-functions}, set up to
+define a particular frame parameter according to the appropriate
+conditions for each frame.
+
+ It would also be possible to implement window-local bindings. We
+don't know of many situations where they would be useful, and it seems
+that indirect buffers (@pxref{Indirect Buffers}) with buffer-local
+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}.
+
+@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