@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 Free Software Foundation, Inc.
+@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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.
* 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.
-* Future Local Variables:: New kinds of local values we might add some day.
* 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.
* 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
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.
@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
stored in the symbol's @code{variable-documentation} property. The
Emacs help functions (@pxref{Documentation}) look for this property.
-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}.
+If the documentation string begins with the character @samp{*}, Emacs
+allows users to set it interactively using the @code{set-variable}
+command. However, you should nearly always use @code{defcustom}
+instead of @code{defvar} to define such variables, so that users can
+use @kbd{M-x customize} and related commands to set them. In that
+case, it is not necessary to begin the documentation string with
+@samp{*}. @xref{Customization}.
Here are some examples. This form defines @code{foo} but does not
initialize it:
@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 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}.)
+customization method. (Variables can also have bindings that are
+local to each terminal, or to each frame. @xref{Multiple Displays},
+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 buffer-local variable cannot be made frame-local
+(@pxref{Frame-Local Variables}) or terminal-local (@pxref{Multiple
+Displays}).
+
@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.
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}.
+If the variable is terminal-local (@pxref{Multiple Displays}), or
+frame-local (@pxref{Frame-Local Variables}), this function signals an
+error. Such variables cannot have buffer-local bindings as well.
@strong{Warning:} do not use @code{make-local-variable} for a hook
variable. The hook variables are automatically made buffer-local as
@defun kill-all-local-variables
This function eliminates all the buffer-local variable bindings of the
-current buffer except for variables marked as ``permanent.'' As a
-result, the buffer will see the default values of most variables.
+current buffer except for variables marked as ``permanent'' and local
+hook functions that have a non-@code{nil} @code{permanent-local-hook}
+property (@pxref{Setting Hooks}). As a result, the buffer will see
+the default values of most variables.
This function also resets certain other information pertaining to the
buffer: it sets the local keymap to @code{nil}, the syntax table to the
@end example
@end defun
-@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 File Local Variables
@section File Local Variables
@cindex file local variables
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.
@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
@w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking
@code{enable-local-variables} into account (@pxref{Auto Major Mode}).
+This function works by walking the alist stored in
+@code{file-local-variables-alist} and applying each local variable in
+turn. It calls @code{before-hack-local-variables-hook} and
+@code{hack-local-variables-hook} before and after applying the
+variables, respectively.
+
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
- 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.
+@defvar file-local-variables-alist
+This buffer-local variable holds the alist of file-local variable
+settings. Each element of the alist is of the form
+@w{@code{(@var{var} . @var{value})}}, where @var{var} is a symbol of
+the local variable and @var{value} is its value. When Emacs visits a
+file, it first collects all the file-local variables into this alist,
+and then the @code{hack-local-variables} function applies them one by
+one.
+@end defvar
+
+@defvar before-hack-local-variables-hook
+Emacs calls this hook immediately before applying file-local variables
+stored in @code{file-local-variables-alist}.
+@end defvar
+
+@defvar hack-local-variables-hook
+Emacs calls this hook immediately after it finishes applying
+file-local variables stored in @code{file-local-variables-alist}.
+@end defvar
@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
+@cindex directory local variables
+
+ A directory can specify local variable values common to all files in
+that directory; Emacs uses these to create buffer-local bindings for
+those variables in buffers visiting any file in that directory. This
+is useful when the files in the directory belong to some @dfn{project}
+and therefore share the same local variables.
+
+ There are two different methods for specifying directory local
+variables: by putting them in a special file, or by defining a
+@dfn{project class} for that directory.
+
+@defvr Constant dir-locals-file
+This constant is the name of the file where Emacs expects to find the
+directory-local variables. The name of the file is
+@file{.dir-locals.el}@footnote{
+The MS-DOS version of Emacs uses @file{_dir-locals.el} instead, due to
+limitations of the DOS filesystems.
+}. A file by that name in a directory causes Emacs to apply its
+settings to any file in that directory or any of its subdirectories.
+If some of the subdirectories have their own @file{.dir-locals.el}
+files, Emacs uses the settings from the deepest file it finds starting
+from the file's directory and moving up the directory tree. The file
+specifies local variables as a specially formatted list; see
+@ref{Directory Variables, , Per-directory Local Variables, emacs, The
+GNU Emacs Manual}, for more details.
+@end defvr
+
+@defun hack-dir-local-variables
+This function reads the @code{.dir-locals.el} file and stores the
+directory-local variables in @code{file-local-variables-alist} that is
+local to the buffer visiting any file in the directory, without
+applying them. It also stores the directory-local settings in
+@code{dir-locals-class-alist}, where it defines a special class for
+the directory in which @file{.dir-locals.el} file was found. This
+function works by calling @code{dir-locals-set-class-variables} and
+@code{dir-locals-set-directory-class}, described below.
+@end defun
+
+@defun dir-locals-set-class-variables class variables
+This function defines a set of variable settings for the named
+@var{class}, which is a symbol. You can later assign the class to one
+or more directories, and Emacs will apply those variable settings to
+all files in those directories. The list in @var{variables} can be of
+one of the two forms: @code{(@var{major-mode} . @var{alist})} or
+@code{(@var{directory} . @var{list})}. With the first form, if the
+file's buffer turns on a mode that is derived from @var{major-mode},
+then the all the variables in the associated @var{alist} are applied;
+@var{alist} should be of the form @code{(@var{name} . @var{value})}.
+A special value @code{nil} for @var{major-mode} means the settings are
+applicable to any mode.
+
+With the second form of @var{variables}, if @var{directory} is the
+initial substring of the file's directory, then @var{list} is applied
+recursively by following the above rules; @var{list} should be of one
+of the two forms accepted by this function in @var{variables}.
+@end defun
+
+@defun dir-locals-set-directory-class directory class
+This function assigns @var{class} to all the files in @code{directory}
+and its subdirectories. Thereafter, all the variable settings
+specified for @var{class} will be applied to any visited file in
+@var{directory} and its children. @var{class} must have been already
+defined by @code{dir-locals-set-class-variables}
+@end defun
+
+@defvar dir-locals-class-alist
+This alist holds the class symbols and the associated variable
+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}.
+@end defvar
+
+@node Frame-Local Variables
+@section Frame-Local Values for Variables
+@cindex 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.
+
+ 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})))
+@end lisp
+
+@noindent
+This causes the variable @var{var} to be bound to the specified
+@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
stage in the future.
@defun make-obsolete-variable obsolete-name current-name &optional when
-This function makes the byte-compiler warn that the variable
+This function makes the byte compiler warn that the variable
@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, it is
the variable's new name; then the warning message says to use
@var{current-name} instead of @var{obsolete-name}. If @var{current-name}