@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2011 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,
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
@deffn Command make-variable-buffer-local variable
This function marks @var{variable} (a symbol) automatically
buffer-local, so that any subsequent attempt to set it will make it
-local to the current buffer at the time.
+local to the current buffer at the time. Unlike
+@code{make-local-variable}, with which it is often confused, this
+cannot be undone, and affects the behavior of the variable in all
+buffers.
A peculiar wrinkle of this feature is that binding the variable (with
@code{let} or other binding constructs) does not create a buffer-local
@end table
@end defopt
+@defvar inhibit-local-variables-regexps
+This is a list of regular expressions. If a file has a name
+matching an element of this list, then it is not scanned for
+any form of file-local variable. For examples of why you might want
+to use this, @pxref{Auto Major Mode}.
+@end defvar
+
@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{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
HCoop / bpt / emacs.git / blobdiff