@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 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2011 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.
-* Constant Variables:: Certain "variables" have values that never change.
-* 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
+* Global Variables:: Variable values that exist permanently, everywhere.
+* Constant Variables:: Certain "variables" have values that never change.
+* 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
+* 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.
-* Future Local Variables:: New kinds of local values we might add some day.
-* File Local Variables:: Handling local variable lists in files.
-* Variable Aliases:: Variables that are aliases for other variables.
+* 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.
+* 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.
@end menu
@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''
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}.
+changed. It also declares this variable as @dfn{special}, meaning that it
+should always use dynamic scoping rules. Note that @var{symbol} is not
+evaluated; the symbol to be defined must appear explicitly in the
+@code{defvar}.
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.
+evaluated, and @var{symbol}'s value remains unchanged.
+If @var{value} is omitted, the value of @var{symbol} is not changed in any
+case; instead, the only effect of @code{defvar} is to declare locally that this
+variable exists elsewhere and should hence always use dynamic scoping rules.
If @var{symbol} has a buffer-local binding in the current buffer,
@code{defvar} operates on the default value, which is buffer-independent,
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:
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
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).
-As the second form illustrates, however, this is only advisory.
+An example of the use of @code{defconst} is Emacs' definition of
+@code{float-pi}---the mathematical constant @math{pi}, which ought not
+to be changed by anyone (attempts by the Indiana State Legislature
+notwithstanding). As the second form illustrates, however,
+@code{defconst} is only advisory.
@example
@group
-(defconst pi 3.1415 "Pi to five places.")
- @result{} pi
+(defconst float-pi 3.141592653589793 "The value of Pi.")
+ @result{} float-pi
@end group
@group
-(setq pi 3)
- @result{} pi
+(setq float-pi 3)
+ @result{} float-pi
@end group
@group
-pi
+float-pi
@result{} 3
@end group
@end example
@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
@cindex extent
@cindex dynamic scoping
@cindex lexical scoping
- Local bindings in Emacs Lisp have @dfn{indefinite scope} and
+ By default, 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
that any part of the program can potentially access the variable
@dfn{dynamic scoping}. By contrast, most programming languages use
@dfn{lexical scoping}, in which references to a local variable must be
located textually within the function or block that binds the variable.
+Emacs can also support lexical scoping, upon request (@pxref{Lexical
+Binding}).
@cindex CL note---special variables
@quotation
@end quotation
@menu
-* Scope:: Scope means where in the program a value is visible.
+* Scope:: Scope means where in the program a value is visible.
Comparison with other languages.
-* Extent:: Extent means how long in time a value exists.
-* Impl of Scope:: Two ways to implement dynamic scoping.
-* Using Scoping:: How to use dynamic scoping carefully and avoid problems.
+* Extent:: Extent means how long in time a value exists.
+* Impl of Scope:: Two ways to implement dynamic scoping.
+* Using Scoping:: How to use dynamic scoping carefully and avoid problems.
+* Lexical Binding:: Use of lexical scoping.
@end menu
@node Scope
by @code{foo} instead of the one bound by @code{binder}.
@end itemize
-Emacs Lisp uses dynamic scoping because simple implementations of
+Emacs Lisp used dynamic scoping by default 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.
+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.
+Nowadays, Emacs offers both, but the default is still to use exclusively
+dynamic scoping.
@node Extent
@subsection Extent
compiler. Choose the variable's name to avoid name conflicts---don't
use short names like @code{x}.
+
+@node Lexical Binding
+@subsection Use of Lexical Scoping
+
+Emacs Lisp can be evaluated in two different modes: in dynamic binding mode or
+lexical binding mode. In dynamic binding mode, all local variables use dynamic
+scoping, whereas in lexical binding mode variables that have been declared
+@dfn{special} (i.e., declared with @code{defvar} or @code{defconst}) use
+dynamic scoping and all others use lexical scoping.
+
+@defvar lexical-binding
+When non-nil, evaluation of Lisp code uses lexical scoping for non-special
+local variables instead of dynamic scoping. If nil, dynamic scoping is used
+for all local variables. This variable is typically set for a whole Elisp file
+via file local variables (@pxref{File Local Variables}).
+@end defvar
+
+@defun special-variable-p SYMBOL
+Return whether SYMBOL has been declared as a special variable, via
+@code{defvar} or @code{defconst}.
+@end defun
+
+The use of a special variable as a formal argument in a function is generally
+discouraged and its behavior in lexical binding mode is unspecified (it may use
+lexical scoping sometimes and dynamic scoping other times).
+
+Functions like @code{symbol-value}, @code{boundp}, or @code{set} only know
+about dynamically scoped variables, so you cannot get the value of a lexical
+variable via @code{symbol-value} and neither can you change it via @code{set}.
+Another particularity is that code in the body of a @code{defun} or
+@code{defmacro} cannot refer to surrounding lexical variables.
+
+Evaluation of a @code{lambda} expression in lexical binding mode will not just
+return that lambda expression unchanged, as in the dynamic binding case, but
+will instead construct a new object that remembers the current lexical
+environment in which that lambda expression was defined, so that the function
+body can later be evaluated in the proper context. Those objects are called
+@dfn{closures}. They are also functions, in the sense that they are accepted
+by @code{funcall}, and they are represented by a cons cell whose @code{car} is
+the symbol @code{closure}.
+
+@menu
+* Converting to Lexical Binding:: How to start using lexical scoping
+@end menu
+
+@node Converting to Lexical Binding
+@subsubsection Converting a package to use lexical scoping
+
+Lexical scoping, as currently implemented, does not bring many significant
+benefits, unless you are a seasoned functional programmer addicted to
+higher-order functions. But its importance will increase in the future:
+lexical scoping opens up a lot more opportunities for optimization, so
+lexically scoped code is likely to run faster in future Emacs versions, and it
+is much more friendly to concurrency, which we want to add in the near future.
+
+Converting a package to lexical binding is usually pretty easy and should not
+break backward compatibility: just add a file-local variable setting
+@code{lexical-binding} to @code{t} and add declarations of the form
+@code{(defvar @var{VAR})} for every variable which still needs to use
+dynamic scoping.
+
+To find which variables need this declaration, the simplest solution is to
+check the byte-compiler's warnings. The byte-compiler will usually find those
+variables either because they are used outside of a let-binding (leading to
+warnings about reference or assignment to ``free variable @var{VAR}'') or
+because they are let-bound but not used within the let-binding (leading to
+warnings about ``unused lexical variable @var{VAR}'').
+
+In cases where a dynamically scoped variable was bound as a function argument,
+you will also need to move this binding to a @code{let}. These cases are also
+flagged by the byte-compiler.
+
+To silence byte-compiler warnings about unused variables, just use a variable
+name that start with an underscore, which the byte-compiler interpret as an
+indication that this is a variable known not to be used.
+
+In most cases, the resulting code will then work with either setting of
+@code{lexical-binding}, so it can still be used with older Emacsen (which will
+simply ignore the @code{lexical-binding} variable setting).
+
@node Buffer-Local Variables
@section Buffer-Local Variables
@cindex variable, buffer-local
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 Terminals},
+and @xref{Frame-Local Variables}.)
@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
+* 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 buffer-local values.
@end menu
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
+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, 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 Terminals}), 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
@cindex permanent local variable
A buffer-local variable is @dfn{permanent} if the variable name (a
symbol) has a @code{permanent-local} property that is non-@code{nil}.
+Such variables are unaffected by @code{kill-all-local-variables}, and
+their local bindings are therefore not cleared by changing major modes.
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.
@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.
+
+ 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
@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
+(optionally, you can exclude subdirectories; see below).
+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. In @var{alist}, you can use a special
+@var{name}: @code{subdirs}. If the associated value is
+@code{nil}, the alist is only applied to files in the relevant
+directory, not to those in any subdirectories.
+
+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 &optional mtime
+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}.
+
+Emacs uses this function internally when it loads directory variables
+from a @code{.dir-locals.el} file. In that case, the optional
+argument @var{mtime} holds the file modification time (as returned by
+@code{file-attributes}). Emacs uses this time to check stored
+local variables are still valid. If you are assigning a class
+directly, not via a file, this argument should be @code{nil}.
+@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-cache
+This alist holds directory names, their assigned class names, and
+modification times of the associated directory local variables file
+(if there is one). The function @code{dir-locals-set-directory-class}
+updates this list.
+@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
(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
HCoop / bpt / emacs.git / blobdiff