@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
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/variables
@node Variables, Functions, Control Structures, Top
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.
-* 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.
+* 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.
+* 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
@node Constant Variables
@section Variables that Never Change
-@kindex setting-constant
+@cindex @code{setting-constant} error
@cindex keyword symbol
@cindex variable with constant value
@cindex constant variables
@node Void Variables
@section When a Variable is ``Void''
-@kindex void-variable
+@cindex @code{void-variable} error
@cindex void variable
If you have never given a symbol any value as a global variable, we
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,
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
is a user option. Aliases of user options are also user options.
@end defun
-@kindex variable-interactive
+@cindex @code{variable-interactive} property
+@findex set-variable
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
@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}, @code{defcustom} 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
@dfn{buffer-local} bindings, which apply only in one buffer. Having
different values for a variable in different buffers is an important
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}.)
+local to each terminal. @xref{Multiple Terminals}.)
@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}).
+ A buffer-local variable cannot be made terminal-local
+(@pxref{Multiple Terminals}).
@node Creating Buffer-Local
@subsection Creating and Deleting Buffer-Local Bindings
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 Terminals}), or
-frame-local (@pxref{Frame-Local Variables}), this function signals an
-error. Such variables cannot have buffer-local bindings as well.
+If the variable is terminal-local (@pxref{Multiple Terminals}), 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
@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.
@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.
+variables, respectively. It only calls the before-hook if the alist
+is non-@code{nil}; it always calls the other hook. This
+function ignores a @samp{mode} element if it specifies the same major
+mode as the buffer already has.
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.
+this function does is return a symbol specifying the major mode,
+if the @w{@samp{-*-}} line or the local variables list specifies one,
+and @code{nil} otherwise. It does not set the mode nor any other
+file-local variable.
@end defun
@defvar file-local-variables-alist
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.
+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
@code{dir-locals-set-directory-class}, described below.
@end defun
+@defun hack-dir-local-variables-non-file-buffer
+This function looks for directory-local variables, and immediately
+applies them in the current buffer. It is intended to be called in
+the mode commands for non-file buffers, such as Dired buffers, to let
+them obey directory-local variable settings. For non-file buffers,
+Emacs looks for directory-local variables in @code{default-directory}
+and its parent directories.
+@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
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.
+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
of the two forms accepted by this function in @var{variables}.
@end defun
-@defun dir-locals-set-directory-class directory class
+@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}
+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
@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}.
+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
@cindex variable aliases
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
+(setq undo-limit 1000.0)
+@error{} Wrong type argument: integerp, 1000.0
@end example
-
-@ignore
- arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e
-@end ignore