@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,
+@c 2000, 2003, 2004
+@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.
* 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.
+* Variables with Restricted Values:: Non-constant variables whose value can
+ @emph{not} be an arbitrary Lisp object.
@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
- 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{:}.
-
- The symbols @code{nil} and @code{t} @emph{always} evaluate to
-themselves. These symbols cannot be rebound, nor can their values be
-changed. Any 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.
All of the @var{value-form}s in @var{bindings} are evaluated in the
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.
+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
-(setq Y 2)
+(setq y 2)
@result{} 2
@end group
@group
-(let ((Y 1)
- (Z Y))
- (list Y Z))
+(let ((y 1)
+ (z y))
+ (list y z))
@result{} (1 2)
@end group
@end example
@example
@group
-(setq Y 2)
+(setq y 2)
@result{} 2
@end group
@group
-(let* ((Y 1)
- (Z Y)) ; @r{Use the just-established value of @code{Y}.}
- (list Y Z))
+(let* ((y 1)
+ (z y)) ; @r{Use the just-established value of @code{y}.}
+ (list y z))
@result{} (1 1)
@end group
@end example
@end itemize
Variables can also have buffer-local bindings (@pxref{Buffer-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.
+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
+@anchor{Definition of 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
-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 variable defines the limit on the total number of local variable
+bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,,
+Cleaning Up from 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.
+@code{max-lisp-eval-depth} provides another limit on depth of nesting.
+@xref{Definition of max-lisp-eval-depth,, Eval}.
- The default value is 600.
-
- @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
@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
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} 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 even if
-the variable already has a value.
-
-If @var{symbol} has a buffer-local binding in the current buffer,
-@code{defvar} sets the default (buffer-independent) value, not the
-buffer-local value. @xref{Buffer-Local Variables}.
+@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}. However, it is better to use @code{defcustom}
-instead of @code{defvar}, for user option variables, to 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:
at top level in a file where its value does not matter.
@end defspec
-@defspec defconst symbol [value [doc-string]]
+@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 standard
global value, established here, that should not be changed by the user
symbol to be defined must appear explicitly in the @code{defconst}.
@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 has 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 the symbol buffer-local if it is defined with @code{defconst}.
+@var{symbol} to the result. 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,
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 the @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
-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.
+forms are used while the variable has a local binding (made with
+@code{let}, or a function argument), they set the local-binding's
+value; the top-level binding is not changed. This is not 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:
@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 uninitialized,
+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
@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{})
@end example
@noindent
-This code sets the variable, then alters it, but only if the variable
-had been @code{ni}. 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.
+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 one.
+A @code{void-variable} error is signaled if the current binding of
+@var{symbol} is void.
@end defun
@node Setting Variables
x ; @r{@code{x} now has a global value.}
@result{} 3
@group
-(let ((x 5))
+(let ((x 5))
(setq x 6) ; @r{The local binding of @code{x} is set.}
x)
@result{} 6
@group
(setq x 10 ; @r{Notice that @code{x} is set before}
y (1+ x)) ; @r{the value of @code{y} is computed.}
- @result{} 11
+ @result{} 11
@end group
@end example
@end defspec
One other function for setting a variable is designed to add
an element to a list if it is not already present in the list.
-@defun add-to-list symbol element
+@defun add-to-list symbol element &optional append
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. It returns the resulting list, whether updated or not. The
value of @var{symbol} had better be a list already before the call.
+Membership is tested using @code{equal}.
+
+Normally, if @var{element} is added, it is added to the front of
+@var{symbol}, but if the optional argument @var{append} is
+non-@code{nil}, it is added at the end.
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:
@cindex scope
@cindex extent
@cindex dynamic scoping
+@cindex lexical 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
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 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.
+ 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
@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
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. If you set the variable
-in a buffer that does not have a buffer-local binding for it, this sets
-the default binding, so the new value is visible in all the buffers that
-see the default binding.
+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 default 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
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 default value of the variable as usual,
-but any @code{setq} creates a buffer-local binding for the current
+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 binding untouched. The default value can no longer be
-changed with @code{setq} in this buffer; you need to use
-@code{setq-default} to do that.
-
- @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.
-
- 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. Here is an
-example of what to avoid:
+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 buffer-local or frame-local
+bindings in one or more buffers, @code{let} rebinds the binding that's
+currently in effect. For instance, if the current buffer has a
+buffer-local value, @code{let} temporarily rebinds that. If no
+buffer-local or frame-local bindings are in effect, @code{let} rebinds
+the default value. If inside the @code{let} you then change to a
+different current buffer in which a different binding is in effect,
+you won't see the @code{let} binding any more. And if you exit the
+@code{let} while still in the other buffer, you won't see the
+unbinding occur (though it will occur properly). Here is an example
+to illustrate:
@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.}
-@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}.}
+foo @result{} 'g ; @r{exiting restored the local value in buffer @samp{a},}
+ ; @r{but we don't see that in buffer @samp{b}}
@end group
-@end example
-
-@noindent
-But @code{save-excursion} as shown here avoids the problem:
-
-@example
@group
-(let ((foo 'temp))
- (save-excursion
- (set-buffer "b")
- @var{body}@dots{}))
+(set-buffer "a") ; @r{verify the local value was restored}
+foo @result{} '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.
+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. Instead, use @code{make-local-hook}. @xref{Hooks}.
+@strong{Warning:} 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.
-The value returned is @var{variable}.
+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}), while the variable does not have a @code{let}-style
+binding that was made in the current buffer, does so.
+
+If @var{variable} does not have a default value, then calling this
+command will give it a default value of @code{nil}. If @var{variable}
+already has a default value, that value remains unchanged.
+Subsequently calling @code{makunbound} on @var{variable} will result
+in a void buffer-local value and leave the default value unaffected.
-@strong{Note:} It is a mistake to 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.
+The value returned is @var{variable}.
-The main use of @code{make-variable-buffer-local} is when a variable is
-used for internal purposes, and the Lisp program depends on having
-separate values in separate buffers.
+@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
@code{nil}.
@end defun
+@defun local-variable-if-set-p variable &optional buffer
+This returns @code{t} if @var{variable} will become buffer-local in
+buffer @var{buffer} (which defaults to the current buffer) if it is
+set there.
+@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
+
@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 buffer-local variables.}
+ ;; @r{Next, non-built-in buffer-local variables.}
;; @r{This one is buffer-local and void:}
foobar
;; @r{This one is buffer-local and nonvoid:}
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} (@pxref{Major Mode Conventions}).
+@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. It is also useful for buffer-specific minor modes
+that should be forgotten if the user changes the 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 buffer-local variable is @dfn{permanent} if the variable name (a
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
-buffer-local value.
+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
@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 @var{variable} does not have a default value, then calling this
+command will give it a default value of @code{nil}. If @var{variable}
+already has a default value, that value remains unchanged.
+
+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.
+
+This command returns @var{variable}.
+@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 &optional 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 non-@code{nil}, it specifies the
+documentation for @var{alias-var}; otherwise, the alias gets the same
+documentation as @var{base-var} has, if any, unless @var{base-var} is
+itself an alias, in which case @var{alias-var} gets the documentation
+of the variable at the end of the chain of aliases.
+
+This function returns @var{base-var}.
+@end defun
+
+Variables aliases are often used prior to replacing an old name for a variable
+with a new name. To allow some time for existing code to adapt to this change,
+@code{make-obsolete-variable} declares that the old name is obsolete and
+therefore that it may be removed at some stage in the future.
+
+@defmac make-obsolete-variable variable new &optional when
+This macro makes the byte-compiler warn that symbol @var{variable} is
+obsolete and that symbol @var{new} should be used instead. If
+@var{new} is a string, this is the message and there is no replacement
+variable. If it is provided, @var{when} should be a string indicating
+when the variable was first made obsolete, for example a date or a
+release number.
+@end defmac
+
+You can make two variables synonyms and declare one obsolete at the
+same time using the macro @code{define-obsolete-variable-alias}.
+
+@defmac define-obsolete-variable-alias variable new &optional when docstring
+This macro defines the symbol @var{variable} as a variable alias for
+symbol @var{new} and warns that @var{variable} is obsolete. If it is
+provided, @var{when} should be a string indicating when @var{variable}
+was first made obsolete. The optional argument @var{docstring}
+specifies the documentation string for @var{variable}. If
+@var{docstring} is omitted or nil, @var{variable} uses the
+documentation string of @var{new} unless it already has one.
+@end defmac
+
+@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}.
+
+This function signals a @code{cyclic-variable-indirection} error if
+there is a loop in the chain of symbols.
+@end defun
+
+@example
+(defvaralias 'foo 'bar)
+(indirect-variable 'foo)
+ @result{} bar
+(indirect-variable 'bar)
+ @result{} bar
+(setq bar 2)
+bar
+ @result{} 2
+@group
+foo
+ @result{} 2
+@end group
+(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. @xref{File variables, ,
+Local Variables in Files, emacs, The GNU Emacs Manual}, for basic
+information about file local variables.
+
+@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 mode-only
+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. However, this
+function does not look for the @samp{mode:} local variable in the
+@w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking
+@code{enable-local-variables} into account.
+
+If the optional argument @var{mode-only} is non-@code{nil}, then all
+this function does is return @code{t} if the @w{@samp{-*-}} line
+specifies a mode and @code{nil} otherwise. It does not set the mode
+nor any other file local variable. It does not check whether a mode
+is specified in the local variables list at the end of the file.
+@end defun
+
+ If a file local variable list could specify a function that would
+be called later, or an expression that would 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{-command},
+@samp{-frame-alist}, @samp{-function}, @samp{-functions},
+@samp{-hook}, @samp{-hooks}, @samp{-form}, @samp{-forms}, @samp{-map},
+@samp{-map-alist}, @samp{-mode-alist}, @samp{-program}, 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. The variables @samp{font-lock-keywords},
+@samp{font-lock-keywords-[0-9]}, and
+@samp{font-lock-syntactic-keywords} cannot be set in a local variable
+list, either. These rules can be overridden by giving the variable's
+name a non-@code{nil} @code{safe-local-variable} property. If one
+gives it a @code{safe-local-variable} property of @code{t}, then one
+can give the variable any file local value. One can also give any
+symbol, including the above, a @code{safe-local-variable} property
+that is a function taking exactly one argument. In that case, giving
+a variable with that name a file local value is only allowed if the
+function returns non-@code{nil} when called with that value as
+argument.
+
+ 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
+
+@defun risky-local-variable-p sym &optional val
+If @var{val} is non-@code{nil}, returns non-@code{nil} if giving
+@var{sym} a file local value of @var{val} would be risky, for any of
+the reasons stated above. If @var{val} is @code{nil} or omitted, only
+returns @code{nil} if @var{sym} can be safely assigned any file local
+value whatsoever.
+@end defun
+
+ 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
+
+ Text properties are also potential loopholes, since their values
+could include functions to call. So Emacs discards all text
+properties from string values specified in a file's local variables
+list.
+
+@node Variables with Restricted Values
+@section Variables with Restricted Values
+
+ Ordinary Lisp variables can be assigned any value that is a valid
+Lisp object. However, certain Lisp variables are not defined in Lisp,
+but in C. Most of these variables are defined in the C code using
+@code{DEFVAR_LISP}. Like variables defined in Lisp, these can take on
+any value. However, some variables are defined using
+@code{DEFVAR_INT} or @code{DEFVAR_BOOL}. @xref{Defining Lisp
+variables in C,, Writing Emacs Primitives}, in particular the
+description of functions of the type @code{syms_of_@var{filename}},
+for a brief discussion of the C implementation.
+
+ Variables of type @code{DEFVAR_BOOL} can only take on the values
+@code{nil} or @code{t}. Attempting to assign them any other value
+will set them to @code{t}:
+
+@example
+(let ((display-hourglass 5))
+ display-hourglass)
+ @result{} t
+@end example
+
+@defvar byte-boolean-vars
+This variable holds a list of all variables of type @code{DEFVAR_BOOL}.
+@end defvar
+
+ Variables of type @code{DEFVAR_INT} can only take on integer values.
+Attempting to assign them any other value will result in an error:
+
+@example
+(setq window-min-height 5.0)
+@error{} Wrong type argument: integerp, 5.0
+@end example
+
+@ignore
+ arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e
+@end ignore