@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/variables
@node Variables, Functions, Control Structures, Top
In Lisp, unlike most programming languages, programs are represented
primarily as Lisp objects and only secondarily as text. The Lisp
-objects used for variables are symbols: the symbol name is the variable
-name, and the variable's value is stored in the value cell of the
-symbol. The use of a symbol as a variable is independent of its use as
-a function name. @xref{Symbol Components}.
+objects used for variables are symbols: the symbol name is the
+variable name, and the variable's value is stored in the value cell of
+the symbol. The use of a symbol as a variable is independent of its
+use as a function name. @xref{Symbol Components}.
- The Lisp objects that constitute a Lisp program determine the textual
-form of the program---it is simply the read syntax for those Lisp
-objects. This is why, for example, a variable in a textual Lisp program
-is written using the read syntax for the symbol that represents the
-variable.
+ The textual form of a Lisp program is given by the read syntax of
+the Lisp objects that constitute the program. Hence, a variable in a
+textual Lisp program is written using the read syntax for the symbol
+representing the variable.
@menu
* Global Variables:: Variable values that exist permanently, everywhere.
* File Local Variables:: Handling local variable lists in files.
* Directory Local Variables:: Local variables common to all files in a directory.
* Frame-Local Variables:: Frame-local bindings for variables.
-* Future Local Variables:: New kinds of local values we might add some day.
* Variable Aliases:: Variables that are aliases for other variables.
* Variables with Restricted Values:: Non-constant variables whose value can
@emph{not} be an arbitrary Lisp object.
@noindent
gives the variable @code{x} the value @code{(a b)}. Note that
-@code{setq} does not evaluate its first argument, the name of the
-variable, but it does evaluate the second argument, the new value.
+@code{setq} is a special form (@pxref{Special Forms}); it does not
+evaluate its first argument, the name of the variable, but it does
+evaluate the second argument, the new value.
- Once the variable has a value, you can refer to it by using the symbol
-by itself as an expression. Thus,
+ Once the variable has a value, you can refer to it by using the
+symbol itself as an expression. Thus,
@example
@group
@code{nil} otherwise.
@end defun
+These constants are fundamentally different from the ``constants''
+defined using the @code{defconst} special form (@pxref{Defining
+Variables}). A @code{defconst} form serves to inform human readers
+that you do not intend to change the value of a variable, but Emacs
+does not raise an error if you actually change it.
+
@node Local Variables
@section Local Variables
@cindex binding local variables
variables; these last until exit from the @code{let} form.
@cindex shadowing of variables
- Establishing a local value saves away the previous value (or lack of
-one) of the variable. When the life span of the local value is over,
-the previous value is restored. In the mean time, we say that the
-previous value is @dfn{shadowed} and @dfn{not visible}. Both global and
-local values may be shadowed (@pxref{Scope}).
+ Establishing a local value saves away the variable's previous value
+(or lack of one). We say that the previous value is @dfn{shadowed}
+and @dfn{not visible}. Both global and local values may be shadowed
+(@pxref{Scope}). After the life span of the local value is over, the
+previous value (or lack of one) is restored.
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
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.
-Entry to a function, or a special form such as @code{let}, creates the
-local binding; exit from the function or from the @code{let} removes the
-local binding. As long as the local binding lasts, the variable's value
-is stored within it. Use of @code{setq} or @code{set} while there is a
+Entering a function, or a special form such as @code{let}, creates the
+local binding; exiting the function or the @code{let} removes the
+local binding. While the local binding lasts, the variable's value is
+stored within it. Using @code{setq} or @code{set} while there is a
local binding stores a different value into the local binding; it does
not create a new binding.
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
+(@pxref{Multiple Terminals}). 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
+@defopt 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{Cleanups,,
-Cleaning Up from Nonlocal Exits}) that are allowed before signaling an
-error (with data @code{"Variable binding depth exceeds
+bindings and @code{unwind-protect} cleanups (see @ref{Cleanups,,
+Cleaning Up from Nonlocal Exits}) that are allowed before Emacs
+signals 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
The default value is 1000. 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
+@end defopt
@node Void Variables
@section When a Variable is ``Void''
at top level in a file where its value does not matter.
@end defspec
+@cindex constant variables
@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
@item @dots{}-flag
The value is significant only as to whether it is @code{nil} or not.
Since such variables often end up acquiring more values over time,
-this convetion is not strongly recommended.
+this convention is not strongly recommended.
@item @dots{}-program
The value is a program name.
@end table
When you define a variable, always consider whether you should mark
-it as ``risky''; see @ref{File Local Variables}.
+it as ``safe'' or ``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
additional, unusual kinds of variable binding, such as
@dfn{buffer-local} bindings, which apply only in one buffer. Having
different values for a variable in different buffers is an important
-customization method. (A few variables have bindings that are local
-to each terminal; see @ref{Multiple Displays}. You can also have
-frame-local bindings for variables; see @ref{Frame-Local Variables}.)
+customization method. (Variables can also have bindings that are
+local to each terminal, or to each frame. @xref{Multiple Terminals},
+and @xref{Frame-Local Variables}.)
@menu
* Intro to Buffer-Local:: Introduction and concepts.
values when you visit the file. @xref{File Variables,,, emacs, The
GNU Emacs Manual}.
- A variable cannot be both buffer-local and frame-local
+ A buffer-local variable cannot be made frame-local
(@pxref{Frame-Local Variables}) or terminal-local (@pxref{Multiple
-Displays}).
+Terminals}).
@node Creating Buffer-Local
@subsection Creating and Deleting Buffer-Local Bindings
@var{variable} (a symbol). Other buffers are not affected. The value
returned is @var{variable}.
-@c Emacs 19 feature
The buffer-local value of @var{variable} starts out as the same value
@var{variable} previously had. If @var{variable} was void, it remains
void.
@group
;; @r{In buffer @samp{b2}, the value hasn't changed.}
-(save-excursion
- (set-buffer "b2")
+(with-current-buffer "b2"
foo)
@result{} 5
@end group
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 (@pxref{Multiple Displays}), or
+If the variable is terminal-local (@pxref{Multiple Terminals}), or
frame-local (@pxref{Frame-Local Variables}), this function signals an
error. Such variables cannot have buffer-local bindings as well.
A file can specify local variable values; Emacs uses these to create
buffer-local bindings for those variables in the buffer visiting that
file. @xref{File variables, , Local Variables in Files, emacs, The
-GNU Emacs Manual}, for basic information about file local variables.
-This section describes the functions and variables that affect
-processing of file local variables.
+GNU Emacs Manual}, for basic information about file-local variables.
+This section describes the functions and variables that affect how
+file-local variables are processed.
+
+ If a file-local variable could specify an arbitrary function or Lisp
+expression that would be called later, visiting a file could take over
+your Emacs. Emacs protects against this by automatically setting only
+those file-local variables whose specified values are known to be
+safe. Other file-local variables are set only if the user agrees.
+
+ For additional safety, @code{read-circle} is temporarily bound to
+@code{nil} when Emacs reads file-local variables (@pxref{Input
+Functions}). This prevents the Lisp reader from recognizing circular
+and shared Lisp structures (@pxref{Circular Objects}).
@defopt enable-local-variables
-This variable controls whether to process file local variables.
+This variable controls whether to process file-local variables.
The possible values are:
@table @asis
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 or
the local variables list specifies a mode and @code{nil} otherwise.
-It does not set the mode nor any other file local variable.
+It does not set the mode nor any other file-local variable.
@end defun
@defvar file-local-variables-alist
file-local variables stored in @code{file-local-variables-alist}.
@end defvar
- If a file local variable 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. Emacs takes several
-measures to prevent this.
-
@cindex safe local variable
You can specify safe values for a variable with a
-@code{safe-local-variable} property. The property has to be
-a function of one argument; any value is safe if the function
-returns non-@code{nil} given that value. Many commonly encountered
-file variables standardly have @code{safe-local-variable} properties,
-including @code{fill-column}, @code{fill-prefix}, and
-@code{indent-tabs-mode}. For boolean-valued variables that are safe,
-use @code{booleanp} as the property value. Lambda expressions should
-be quoted so that @code{describe-variable} can display the predicate.
+@code{safe-local-variable} property. The property has to be a
+function of one argument; any value is safe if the function returns
+non-@code{nil} given that value. Many commonly-encountered file
+variables have @code{safe-local-variable} properties; these include
+@code{fill-column}, @code{fill-prefix}, and @code{indent-tabs-mode}.
+For boolean-valued variables that are safe, use @code{booleanp} as the
+property value. Lambda expressions should be quoted so that
+@code{describe-variable} can display the predicate.
@defopt safe-local-variable-values
This variable provides another way to mark some variable values as
where @var{var} is a variable name and @var{val} is a value which is
safe for that variable.
-When Emacs asks the user whether or not to obey a set of file local
+When Emacs asks the user whether or not to obey a set of file-local
variable specifications, the user can choose to mark them as safe.
Doing so adds those variable/value pairs to
@code{safe-local-variable-values}, and saves it to the user's custom
Text properties are also potential loopholes, since their values
could include functions to call. So Emacs discards all text
-properties from string values specified for file local variables.
+properties from string values specified for file-local variables.
@node Directory Local Variables
@section Directory Local Variables
settings. It is updated by @code{dir-locals-set-class-variables}.
@end defvar
-@defvar dir-locals-directory-alist
-This alist holds directory names and their assigned class names. It
-is updated by @code{dir-locals-set-directory-class}.
+@defvar dir-locals-directory-cache
+This alist holds directory names, their assigned class names, and
+modification times of the associated directory local variables file.
+It is updated by @code{dir-locals-set-directory-class}.
@end defvar
@node Frame-Local Variables
In addition to buffer-local variable bindings (@pxref{Buffer-Local
Variables}), Emacs supports @dfn{frame-local} bindings. A frame-local
binding for a variable is in effect in a frame for which it was
-defined. Note that you cannot have frame-local bindings for a
-variable that has a buffer-local binding.
+defined.
- To define a frame-specific binding for a variable @var{var} in frame
-@var{frame}, set the @var{var} frame parameter for that frame:
+ In practice, frame-local variables have not proven very useful.
+Ordinary frame parameters are generally used instead (@pxref{Frame
+Parameters}). The function @code{make-variable-frame-local}, which
+was used to define frame-local variables, has been deprecated since
+Emacs 22.2. However, you can still define a frame-specific binding
+for a variable @var{var} in frame @var{frame}, by setting the
+@var{var} frame parameter for that frame:
@lisp
(modify-frame-parameters @var{frame} '((@var{var} . @var{value})))
@noindent
This causes the variable @var{var} to be bound to the specified
-@var{value} in the named @var{frame}. @xref{Parameter Access,
-modify-frame-parameters}.
-
-@findex make-variable-frame-local@r{, deprecated}
- Use of @code{make-variable-frame-local} for defining frame-local
-bindings is deprecated since Emacs 22.2.
-
- To check the frame-specific values of such variables, use
-@code{frame-parameter} (@pxref{Parameter Access, frame-parameter}).
-
-@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.
+@var{value} in the named @var{frame}. To check the frame-specific
+values of such variables, use @code{frame-parameter}. @xref{Parameter
+Access}.
+
+ Note that you cannot have a frame-local binding for a variable that
+has a buffer-local binding.
@node Variable Aliases
@section Variable Aliases
HCoop / bpt / emacs.git / blobdiff