@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
@chapter Variables
@cindex variable
A @dfn{variable} is a name used in a program to stand for a value.
-Nearly all programming languages have variables of some sort. In the
-text of a Lisp program, variables are written using the syntax for
-symbols.
-
- 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}.
-
- 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
+In Lisp, each variable is represented by a Lisp symbol
+(@pxref{Symbols}). The variable name is simply the symbol's name, and
+the variable's value is stored in the symbol's value cell@footnote{To
+be precise, under the default @dfn{dynamic binding} rules the value
+cell always holds the variable's current value, but this is not the
+case under @dfn{lexical binding} rules. @xref{Variable Scoping}, for
+details.}. @xref{Symbol Components}. In Emacs Lisp, the use of a
+symbol as a variable is independent of its use as a function name.
+
+ As previously noted in this manual, a Lisp program is represented
+primarily by Lisp objects, and only secondarily as text. The textual
+form of a Lisp program is given by the read syntax of the Lisp objects
+that constitute the program. Hence, the textual form of a variable in
+a 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.
-* 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
@cindex global binding
Global variables have values that last until explicitly superseded
-with new values. Sometimes it is useful to create variable values that
-exist temporarily---only until a certain part of the program finishes.
-These values are called @dfn{local}, and the variables so used are
-called @dfn{local variables}.
-
- For example, when a function is called, its argument variables receive
-new local values that last until the function exits. The @code{let}
-special form explicitly establishes new local values for specified
-variables; these last until exit from the @code{let} form.
-
-@cindex shadowing of variables
- 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
-previous local values, that are shadowed. To model this behavior, we
-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.
-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.
+with new values. Sometimes it is useful to give a variable a
+@dfn{local value}---a value that takes effect only within a certain
+part of a Lisp program. When a variable has a local value, we say
+that it is @dfn{locally bound} to that value, and that it is a
+@dfn{local variable}.
+
+ For example, when a function is called, its argument variables
+receive local values, which are the actual arguments supplied to the
+function call; these local bindings take effect within the body of the
+function. To take another example, the @code{let} special form
+explicitly establishes local bindings for specific variables, which
+take effect within the body of the @code{let} form.
We also speak of the @dfn{global binding}, which is where
(conceptually) the global value is kept.
+@cindex shadowing of variables
+ Establishing a local binding saves away the variable's previous
+value (or lack of one). We say that the previous value is
+@dfn{shadowed}. Both global and local values may be shadowed. If a
+local binding is in effect, using @code{setq} on the local variable
+stores the specified value in the local binding. When that local
+binding is no longer in effect, the previously shadowed value (or lack
+of one) comes back.
+
@cindex current binding
- A variable can have more than one local binding at a time (for
-example, if there are nested @code{let} forms that bind it). In such a
-case, the most recently created local binding that still exists is the
-@dfn{current binding} of the variable. (This rule is called
-@dfn{dynamic scoping}; see @ref{Variable Scoping}.) If there are no
-local bindings, the variable's global binding is its current binding.
-We sometimes call the current binding the @dfn{most-local existing
-binding}, for emphasis. Ordinary evaluation of a symbol always returns
-the value of its current binding.
-
- The special forms @code{let} and @code{let*} exist to create
-local bindings.
+ A variable can have more than one local binding at a time (e.g.@: if
+there are nested @code{let} forms that bind the variable). The
+@dfn{current binding} is the local binding that is actually in effect.
+It determines the value returned by evaluating the variable symbol,
+and it is the binding acted on by @code{setq}.
+
+ For most purposes, you can think of the current binding as the
+``innermost'' local binding, or the global binding if there is no
+local binding. To be more precise, a rule called the @dfn{scoping
+rule} determines where in a program a local binding takes effect. The
+default scoping rule in Emacs Lisp is called @dfn{dynamic scoping},
+which simply states that the current binding at any given point in the
+execution of a program is the most recently-created binding for that
+variable that still exists. For details about dynamic scoping, and an
+alternative scoping rule called @dfn{lexical scoping}, @xref{Variable
+Scoping}.
+
+ The special forms @code{let} and @code{let*} exist to create local
+bindings:
@defspec let (bindings@dots{}) forms@dots{}
-This special form binds variables according to @var{bindings} and then
-evaluates all of the @var{forms} in textual order. The @code{let}-form
-returns the value of the last form in @var{forms}.
+This special form sets up local bindings for a certain set of
+variables, as specified by @var{bindings}, and then evaluates all of
+the @var{forms} in textual order. Its return value is the value of
+the last form in @var{forms}.
Each of the @var{bindings} is either @w{(i) a} symbol, in which case
-that symbol is bound to @code{nil}; or @w{(ii) a} list of the form
-@code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is
-bound to the result of evaluating @var{value-form}. If @var{value-form}
-is omitted, @code{nil} is used.
+that symbol is locally bound to @code{nil}; or @w{(ii) a} list of the
+form @code{(@var{symbol} @var{value-form})}, in which case
+@var{symbol} is locally bound to the result of evaluating
+@var{value-form}. If @var{value-form} is omitted, @code{nil} is used.
All of the @var{value-form}s in @var{bindings} are evaluated in the
order they appear and @emph{before} binding any of the symbols to them.
(setq y 2)
@result{} 2
@end group
+
@group
(let ((y 1)
(z y))
This special form is like @code{let}, but it binds each variable right
after computing its local value, before computing the local value for
the next variable. Therefore, an expression in @var{bindings} can
-reasonably refer to the preceding symbols bound in this @code{let*}
-form. Compare the following example with the example above for
-@code{let}.
+refer to the preceding symbols bound in this @code{let*} form.
+Compare the following example with the example above for @code{let}.
@example
@group
(setq y 2)
@result{} 2
@end group
+
@group
(let* ((y 1)
(z y)) ; @r{Use the just-established value of @code{y}.}
Variables}); a few variables have terminal-local bindings
(@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.
+``where'' you are in Emacs.
@defopt max-specpdl-size
@anchor{Definition of max-specpdl-size}
@code{max-lisp-eval-depth} provides another limit on depth of nesting.
@xref{Definition of max-lisp-eval-depth,, Eval}.
-The default value is 1000. Entry to the Lisp debugger increases the
+The default value is 1300. 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 defopt
@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
-say that that symbol's global value is @dfn{void}. In other words, the
-symbol's value cell does not have any Lisp object in it. If you try to
-evaluate the symbol, you get a @code{void-variable} error rather than
-a value.
-
- Note that a value of @code{nil} is not the same as void. The symbol
-@code{nil} is a Lisp object and can be the value of a variable just as any
-other object can be; but it is @emph{a value}. A void variable does not
-have any value.
-
- After you have given a variable a value, you can make it void once more
-using @code{makunbound}.
+ We say that a variable is void if its symbol has an unassigned value
+cell (@pxref{Symbol Components}). Under Emacs Lisp's default dynamic
+binding rules (@pxref{Variable Scoping}), the value cell stores the
+variable's current (local or global) value. Note that an unassigned
+value cell is @emph{not} the same as having @code{nil} in the value
+cell. The symbol @code{nil} is a Lisp object and can be the value of
+a variable, just as any other object can be; but it is still a value.
+If a variable is void, trying to evaluate the variable signals a
+@code{void-variable} error rather than a value.
+
+ Under lexical binding rules, the value cell only holds the
+variable's global value, i.e.@: the value outside of any lexical
+binding construct. When a variable is lexically bound, the local value
+is determined by the lexical environment; the variable may have a
+local value if its symbol's value cell is unassigned.
@defun makunbound symbol
-This function makes the current variable binding of @var{symbol} void.
-Subsequent attempts to use this symbol's value as a variable will signal
-the error @code{void-variable}, unless and until you set it again.
+This function empties out the value cell of @var{symbol}, making the
+variable void. It returns @var{symbol}.
-@code{makunbound} returns @var{symbol}.
+If @var{symbol} has a dynamic local binding, @code{makunbound} voids
+the current binding, and this voidness lasts only as long as the local
+binding is in effect. Afterwards, the previously shadowed local or
+global binding is reexposed; then the variable will no longer be void,
+unless the reexposed binding is void too.
-@example
-@group
-(makunbound 'x) ; @r{Make the global value of @code{x} void.}
- @result{} x
-@end group
-@group
-x
-@error{} Symbol's value as variable is void: x
-@end group
-@end example
-
-If @var{symbol} is locally bound, @code{makunbound} affects the most
-local existing binding. This is the only way a symbol can have a void
-local binding, since all the constructs that create local bindings
-create them with values. In this case, the voidness lasts at most as
-long as the binding does; when the binding is removed due to exit from
-the construct that made it, the previous local or global binding is
-reexposed as usual, and the variable is no longer void unless the newly
-reexposed binding was void all along.
+Here are some examples (assuming dynamic binding is in effect):
@smallexample
@group
@end smallexample
@end defun
- A variable that has been made void with @code{makunbound} is
-indistinguishable from one that has never received a value and has
-always been void.
-
- You can use the function @code{boundp} to test whether a variable is
-currently void.
-
@defun boundp variable
-@code{boundp} returns @code{t} if @var{variable} (a symbol) is not void;
-more precisely, if its current binding is not void. It returns
-@code{nil} otherwise.
+This function returns @code{t} if @var{variable} (a symbol) is not
+void, and @code{nil} if it is void.
+
+Here are some examples (assuming dynamic binding is in effect):
@smallexample
@group
@section Defining Global Variables
@cindex variable definition
- You may announce your intention to use a symbol as a global variable
-with a @dfn{variable definition}: a special form, either @code{defconst}
-or @code{defvar}.
-
- In Emacs Lisp, definitions serve three purposes. First, they inform
-people who read the code that certain symbols are @emph{intended} to be
-used a certain way (as variables). Second, they inform the Lisp system
-of these things, supplying a value and documentation. Third, they
-provide information to utilities such as @code{etags} and
-@code{make-docfile}, which create data bases of the functions and
-variables in a program.
-
- The difference between @code{defconst} and @code{defvar} is primarily
-a matter of intent, serving to inform human readers of whether the value
-should ever change. Emacs Lisp does not restrict the ways in which a
-variable can be used based on @code{defconst} or @code{defvar}
-declarations. However, it does make a difference for initialization:
-@code{defconst} unconditionally initializes the variable, while
-@code{defvar} initializes it only if it is void.
-
-@ignore
- One would expect user option variables to be defined with
-@code{defconst}, since programs do not change them. Unfortunately, this
-has bad results if the definition is in a library that is not preloaded:
-@code{defconst} would override any prior value when the library is
-loaded. Users would like to be able to set user options in their init
-files, and override the default values given in the definitions. For
-this reason, user options must be defined with @code{defvar}.
-@end ignore
+ A @dfn{variable definition} is a construct that announces your
+intention to use a symbol as a global variable. It uses the special
+forms @code{defvar} or @code{defconst}, which are documented below.
+
+ A variable definition serves three purposes. First, it informs
+people who read the code that the symbol is @emph{intended} to be used
+a certain way (as a variable). Second, it informs the Lisp system of
+this, optionally supplying an initial value and a documentation
+string. Third, it provides information to programming tools such as
+@command{etags}, allowing them to find where the variable was defined.
+
+ The difference between @code{defconst} and @code{defvar} is mainly a
+matter of intent, serving to inform human readers of whether the value
+should ever change. Emacs Lisp does not actually prevent you from
+changing the value of a variable defined with @code{defconst}. One
+notable difference between the two forms is that @code{defconst}
+unconditionally initializes the variable, whereas @code{defvar}
+initializes it only if it is originally void.
+
+ To define a customizable variable, you should use @code{defcustom}
+(which calls @code{defvar} as a subroutine). @xref{Customization}.
@defspec defvar symbol [value [doc-string]]
-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}.
+This special form defines @var{symbol} as a variable. Note that
+@var{symbol} is not evaluated; the symbol to be defined should appear
+explicitly in the @code{defvar} form. The variable is marked as
+@dfn{special}, meaning that it should always be dynamically bound
+(@pxref{Variable Scoping}).
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.
+evaluates @var{value} 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.
If @var{symbol} has a buffer-local binding in the current buffer,
@code{defvar} operates on the default value, which is buffer-independent,
@code{eval-defun} arranges to set the variable unconditionally, without
testing whether its value is void.
-If the @var{doc-string} argument appears, it specifies the documentation
-for the variable. (This opportunity to specify documentation is one of
-the main benefits of defining the variable.) The documentation is
-stored in the symbol's @code{variable-documentation} property. The
-Emacs help functions (@pxref{Documentation}) look for this property.
-
-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}.
+If the @var{doc-string} argument is supplied, it specifies the
+documentation string for the variable (stored in the symbol's
+@code{variable-documentation} property). @xref{Documentation}.
Here are some examples. This form defines @code{foo} but does not
initialize it:
@end group
@end example
-The following form changes the documentation string for @code{bar},
-making it a user option, but does not change the value, since @code{bar}
-already has a value. (The addition @code{(1+ nil)} would get an error
-if it were evaluated, but since it is not evaluated, there is no error.)
-
-@example
-@group
-(defvar bar (1+ nil)
- "*The normal weight of a bar.")
- @result{} bar
-@end group
-@group
-bar
- @result{} 23
-@end group
-@end example
-
-Here is an equivalent expression for the @code{defvar} special form:
-
-@example
-@group
-(defvar @var{symbol} @var{value} @var{doc-string})
-@equiv{}
-(progn
- (if (not (boundp '@var{symbol}))
- (setq @var{symbol} @var{value}))
- (if '@var{doc-string}
- (put '@var{symbol} 'variable-documentation '@var{doc-string}))
- '@var{symbol})
-@end group
-@end example
-
The @code{defvar} form returns @var{symbol}, but it is normally used
at top level in a file where its value does not matter.
@end defspec
or by other programs. Note that @var{symbol} is not evaluated; the
symbol to be defined must appear explicitly in the @code{defconst}.
+The @code{defconst} form, like @code{defvar}, marks the variable as
+@dfn{special}, meaning that it should always be dynamically bound
+(@pxref{Variable Scoping}). In addition, it marks the variable as
+risky (@pxref{File Local Variables}).
+
@code{defconst} always evaluates @var{value}, and sets the value of
@var{symbol} to the result. If @var{symbol} does have a buffer-local
binding in the current buffer, @code{defconst} sets the default value,
buffer-local bindings for a symbol that is defined with
@code{defconst}.)
-An example of the use of @code{defconst} is Emacs' definition of
+An example of the use of @code{defconst} is Emacs's 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,
@end example
@end defspec
-@defun user-variable-p variable
-@cindex user option
-This function returns @code{t} if @var{variable} is a user option---a
-variable intended to be set by the user for customization---and
-@code{nil} otherwise. (Variables other than user options exist for the
-internal purposes of Lisp programs, and users need not know about them.)
-
-User option variables are distinguished from other variables either
-though being declared using @code{defcustom}@footnote{They may also be
-declared equivalently in @file{cus-start.el}.} or by the first character
-of their @code{variable-documentation} property. If the property exists
-and is a string, and its first character is @samp{*}, then the variable
-is a user option. Aliases of user options are also user options.
-@end defun
-
-@kindex variable-interactive
- 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
-specified in @code{interactive} (@pxref{Using Interactive}). However,
-this feature is largely obsoleted by @code{defcustom}
-(@pxref{Customization}).
-
- @strong{Warning:} If the @code{defconst} and @code{defvar} special
-forms are used while the variable has a local binding (made with
-@code{let}, or a function argument), they set the local-binding's
-value; the top-level binding is not changed. This is not what you
-usually want. To prevent it, use these special forms at top level in
-a file, where normally no local binding is in effect, and make sure to
-load the file before making a local binding for the variable.
+ @strong{Warning:} If you use a @code{defconst} or @code{defvar}
+special form while the variable has a local binding (made with
+@code{let}, or a function argument), it sets the local binding rather
+than the global binding. This is not what you usually want. To
+prevent this, use these special forms at top level in a file, where
+normally no local binding is in effect, and make sure to load the file
+before making a local binding for the variable.
@node Tips for Defining
@section Tips for Defining Variables Robustly
initialized properly, never in-between. If it is still uninitialized,
reloading the file will initialize it properly. Second, reloading the
file once the variable is initialized will not alter it; that is
-important if the user has run hooks to alter part of the contents (such
-as, to rebind keys). Third, evaluating the @code{defvar} form with
-@kbd{C-M-x} @emph{will} reinitialize the map completely.
+important if the user has run hooks to alter part of the contents
+(such as, to rebind keys). Third, evaluating the @code{defvar} form
+with @kbd{C-M-x} will reinitialize the map completely.
Putting so much code in the @code{defvar} form has one disadvantage:
it puts the documentation string far away from the line which names the
the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on
each form, if you do want to reinitialize the variable.
- But be careful not to write the code like this:
-
-@example
-(defvar my-mode-map nil
- @var{docstring})
-(unless my-mode-map
- (setq my-mode-map (make-sparse-keymap))
- (define-key my-mode-map "\C-c\C-a" 'my-command)
- @dots{})
-@end example
-
-@noindent
-This code sets the variable, then alters it, but it does so in more than
-one step. If the user quits just after the @code{setq}, that leaves the
-variable neither correctly initialized nor void nor @code{nil}. Once
-that happens, reloading the file will not initialize the variable; it
-will remain incomplete.
-
@node Accessing Variables
@section Accessing Variable Values
The usual way to reference a variable is to write the symbol which
-names it (@pxref{Symbol Forms}). This requires you to specify the
-variable name when you write the program. Usually that is exactly what
-you want to do. Occasionally you need to choose at run time which
-variable to reference; then you can use @code{symbol-value}.
+names it. @xref{Symbol Forms}.
+
+ Occasionally, you may want to reference a variable which is only
+determined at run time. In that case, you cannot specify the variable
+name in the text of the program. You can use the @code{symbol-value}
+function to extract the value.
@defun symbol-value symbol
-This function returns the value of @var{symbol}. This is the value in
-the innermost local binding of the symbol, or its global value if it
-has no local bindings.
+This function returns the value stored in @var{symbol}'s value cell.
+This is where the variable's current (dynamic) value is stored. If
+the variable has no local binding, this is simply its global value.
+If the variable is void, a @code{void-variable} error is signaled.
+
+If the variable is lexically bound, the value reported by
+@code{symbol-value} is not necessarily the same as the variable's
+lexical value, which is determined by the lexical environment rather
+than the symbol's value cell. @xref{Variable Scoping}.
@example
@group
@result{} 5
@end group
@end example
-
-A @code{void-variable} error is signaled if the current binding of
-@var{symbol} is void.
@end defun
@node Setting Variables
-@section How to Alter a Variable Value
+@section Setting Variable Values
The usual way to change the value of a variable is with the special
form @code{setq}. When you need to compute the choice of variable at
@defspec setq [symbol form]@dots{}
This special form is the most common method of changing a variable's
value. Each @var{symbol} is given a new value, which is the result of
-evaluating the corresponding @var{form}. The most-local existing
-binding of the symbol is changed.
+evaluating the corresponding @var{form}. The current binding of the
+symbol is changed.
@code{setq} does not evaluate @var{symbol}; it sets the symbol that you
write. We say that this argument is @dfn{automatically quoted}. The
-@samp{q} in @code{setq} stands for ``quoted.''
+@samp{q} in @code{setq} stands for ``quoted''.
The value of the @code{setq} form is the value of the last @var{form}.
@end defspec
@defun set symbol value
-This function sets @var{symbol}'s value to @var{value}, then returns
-@var{value}. Since @code{set} is a function, the expression written for
-@var{symbol} is evaluated to obtain the symbol to set.
-
-The most-local existing binding of the variable is the binding that is
-set; shadowed bindings are not affected.
+This function puts @var{value} in the value cell of @var{symbol}.
+Since it is a function rather than a special form, the expression
+written for @var{symbol} is evaluated to obtain the symbol to set.
+The return value is @var{value}.
+
+When dynamic variable binding is in effect (the default), @code{set}
+has the same effect as @code{setq}, apart from the fact that
+@code{set} evaluates its @var{symbol} argument whereas @code{setq}
+does not. But when a variable is lexically bound, @code{set} affects
+its @emph{dynamic} value, whereas @code{setq} affects its current
+(lexical) value. @xref{Variable Scoping}.
@example
@group
(set '(x y) 'z)
@error{} Wrong type argument: symbolp, (x y)
@end example
-
-Logically speaking, @code{set} is a more fundamental primitive than
-@code{setq}. Any use of @code{setq} can be trivially rewritten to use
-@code{set}; @code{setq} could even be defined as a macro, given the
-availability of @code{set}. However, @code{set} itself is rarely used;
-beginners hardly need to know about it. It is useful only for choosing
-at run time which variable to set. For example, the command
-@code{set-variable}, which reads a variable name from the user and then
-sets the variable, needs to use @code{set}.
-
-@cindex CL note---@code{set} local
-@quotation
-@b{Common Lisp note:} In Common Lisp, @code{set} always changes the
-symbol's ``special'' or dynamic value, ignoring any lexical bindings.
-In Emacs Lisp, all variables and all bindings are dynamic, so @code{set}
-always affects the most local existing binding.
-@end quotation
@end defun
@node Variable Scoping
@section Scoping Rules for Variable Bindings
- A given symbol @code{foo} can have several local variable bindings,
-established at different places in the Lisp program, as well as a global
-binding. The most recently established binding takes precedence over
-the others.
+ When you create a local binding for a variable, that binding takes
+effect only within a limited portion of the program (@pxref{Local
+Variables}). This section describes exactly what this means.
@cindex scope
@cindex extent
-@cindex dynamic scoping
-@cindex lexical scoping
- 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
-binding. @dfn{Extent} refers to @emph{when}, as the program is
-executing, the binding exists. ``Dynamic extent'' means that the binding
-lasts as long as the activation of the construct that established it.
-
- The combination of dynamic extent and indefinite scope is called
-@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.
-
-@cindex CL note---special variables
-@quotation
-@b{Common Lisp note:} Variables declared ``special'' in Common Lisp are
-dynamically scoped, like all variables in Emacs Lisp.
-@end quotation
+ Each local binding has a certain @dfn{scope} and @dfn{extent}.
+@dfn{Scope} refers to @emph{where} in the textual source code the
+binding can be accessed. @dfn{Extent} refers to @emph{when}, as the
+program is executing, the binding exists.
+
+@cindex dynamic binding
+@cindex indefinite scope
+@cindex dynamic extent
+ By default, the local bindings that Emacs creates are @dfn{dynamic
+bindings}. Such a binding has @dfn{indefinite scope}, meaning that
+any part of the program can potentially access the variable binding.
+It also has @dfn{dynamic extent}, meaning that the binding lasts only
+while the binding construct (such as the body of a @code{let} form) is
+being executed.
+
+@cindex lexical binding
+@cindex lexical scope
+@cindex indefinite extent
+ Emacs can optionally create @dfn{lexical bindings}. A lexical
+binding has @dfn{lexical scope}, meaning that any reference to the
+variable must be located textually within the binding construct. It
+also has @dfn{indefinite extent}, meaning that under some
+circumstances the binding can live on even after the binding construct
+has finished executing, by means of special objects called
+@dfn{closures}.
+
+ The following subsections describe dynamic binding and lexical
+binding in greater detail, and how to enable lexical binding in Emacs
+Lisp programs.
@menu
-* 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.
+* Dynamic Binding:: The default for binding local variables in Emacs.
+* Dynamic Binding Tips:: Avoiding problems with dynamic binding.
+* Lexical Binding:: A different type of local variable binding.
+* Using Lexical Binding:: How to enable lexical binding.
@end menu
-@node Scope
-@subsection Scope
+@node Dynamic Binding
+@subsection Dynamic Binding
- Emacs Lisp uses @dfn{indefinite scope} for local variable bindings.
-This means that any function anywhere in the program text might access a
-given binding of a variable. Consider the following function
-definitions:
+ By default, the local variable bindings made by Emacs are dynamic
+bindings. When a variable is dynamically bound, its current binding
+at any point in the execution of the Lisp program is simply the most
+recently-created dynamic local binding for that symbol, or the global
+binding if there is no such local binding.
+
+ Dynamic bindings have indefinite scope and dynamic extent, as shown
+by the following example:
@example
@group
-(defun binder (x) ; @r{@code{x} is bound in @code{binder}.}
- (foo 5)) ; @r{@code{foo} is some other function.}
+(defvar x -99) ; @r{@code{x} receives an initial value of -99.}
+
+(defun getx ()
+ x) ; @r{@code{x} is used ``free'' in this function.}
+
+(let ((x 1)) ; @r{@code{x} is dynamically bound.}
+ (getx))
+ @result{} 1
+
+;; @r{After the @code{let} form finishes, @code{x} reverts to its}
+;; @r{previous value, which is -99.}
+
+(getx)
+ @result{} -99
@end group
+@end example
+
+@noindent
+The function @code{getx} refers to @code{x}. This is a ``free''
+reference, in the sense that there is no binding for @code{x} within
+that @code{defun} construct itself. When we call @code{getx} from
+within a @code{let} form in which @code{x} is (dynamically) bound, it
+retrieves the local value of @code{x} (i.e.@: 1). But when we call
+@code{getx} outside the @code{let} form, it retrieves the global value
+of @code{x} (i.e.@: -99).
+
+ Here is another example, which illustrates setting a dynamically
+bound variable using @code{setq}:
+@example
@group
-(defun user () ; @r{@code{x} is used ``free'' in @code{user}.}
- (list x))
+(defvar x -99) ; @r{@code{x} receives an initial value of -99.}
+
+(defun addx ()
+ (setq x (1+ x))) ; @r{Add 1 to @code{x} and return its new value.}
+
+(let ((x 1))
+ (addx)
+ (addx))
+ @result{} 3 ; @r{The two @code{addx} calls add to @code{x} twice.}
+
+;; @r{After the @code{let} form finishes, @code{x} reverts to its}
+;; @r{previous value, which is -99.}
+
+(addx)
+ @result{} -98
@end group
@end example
- In a lexically scoped language, the binding of @code{x} in
-@code{binder} would never be accessible in @code{user}, because
-@code{user} is not textually contained within the function
-@code{binder}. However, in dynamically-scoped Emacs Lisp, @code{user}
-may or may not refer to the binding of @code{x} established in
-@code{binder}, depending on the circumstances:
+ Dynamic binding is implemented in Emacs Lisp in a simple way. Each
+symbol has a value cell, which specifies its current dynamic value (or
+absence of value). @xref{Symbol Components}. When a symbol is given
+a dynamic local binding, Emacs records the contents of the value cell
+(or absence thereof) in a stack, and stores the new local value in the
+value cell. When the binding construct finishes executing, Emacs pops
+the old value off the stack, and puts it in the value cell.
+
+@node Dynamic Binding Tips
+@subsection Proper Use of Dynamic Binding
+
+ Dynamic binding is a powerful feature, as it allows programs to
+refer to variables that are not defined within their local textual
+scope. However, if used without restraint, this can also make
+programs hard to understand. There are two clean ways to use this
+technique:
@itemize @bullet
@item
-If we call @code{user} directly without calling @code{binder} at all,
-then whatever binding of @code{x} is found, it cannot come from
-@code{binder}.
+If a variable has no global definition, use it as a local variable
+only within a binding construct, e.g.@: the body of the @code{let}
+form where the variable was bound, or the body of the function for an
+argument variable. If this convention is followed consistently
+throughout a program, the value of the variable will not affect, nor
+be affected by, any uses of the same variable symbol elsewhere in the
+program.
@item
-If we define @code{foo} as follows and then call @code{binder}, then the
-binding made in @code{binder} will be seen in @code{user}:
+Otherwise, define the variable with @code{defvar}, @code{defconst}, or
+@code{defcustom}. @xref{Defining Variables}. Usually, the definition
+should be at top-level in an Emacs Lisp file. As far as possible, it
+should include a documentation string which explains the meaning and
+purpose of the variable. You should also choose the variable's name
+to avoid name conflicts (@pxref{Coding Conventions}).
+
+Then you can bind the variable anywhere in a program, knowing reliably
+what the effect will be. Wherever you encounter the variable, it will
+be easy to refer back to the definition, e.g.@: via the @kbd{C-h v}
+command (provided the variable definition has been loaded into Emacs).
+@xref{Name Help,,, emacs, The GNU Emacs Manual}.
+
+For example, it is common to use local bindings for customizable
+variables like @code{case-fold-search}:
@example
@group
-(defun foo (lose)
- (user))
+(defun search-for-abc ()
+ "Search for the string \"abc\", ignoring case differences."
+ (let ((case-fold-search nil))
+ (re-search-forward "abc")))
@end group
@end example
+@end itemize
-@item
-However, if we define @code{foo} as follows and then call @code{binder},
-then the binding made in @code{binder} @emph{will not} be seen in
-@code{user}:
-
-@example
-(defun foo (x)
- (user))
-@end example
+@node Lexical Binding
+@subsection Lexical Binding
-@noindent
-Here, when @code{foo} is called by @code{binder}, it binds @code{x}.
-(The binding in @code{foo} is said to @dfn{shadow} the one made in
-@code{binder}.) Therefore, @code{user} will access the @code{x} bound
-by @code{foo} instead of the one bound by @code{binder}.
-@end itemize
+Optionally, you can create lexical bindings in Emacs Lisp. A
+lexically bound variable has @dfn{lexical scope}, meaning that any
+reference to the variable must be located textually within the binding
+construct.
-Emacs Lisp uses dynamic scoping 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.
-
-@node Extent
-@subsection Extent
-
- @dfn{Extent} refers to the time during program execution that a
-variable name is valid. In Emacs Lisp, a variable is valid only while
-the form that bound it is executing. This is called @dfn{dynamic
-extent}. ``Local'' or ``automatic'' variables in most languages,
-including C and Pascal, have dynamic extent.
-
- One alternative to dynamic extent is @dfn{indefinite extent}. This
-means that a variable binding can live on past the exit from the form
-that made the binding. Common Lisp and Scheme, for example, support
-this, but Emacs Lisp does not.
-
- To illustrate this, the function below, @code{make-add}, returns a
-function that purports to add @var{n} to its own argument @var{m}. This
-would work in Common Lisp, but it does not do the job in Emacs Lisp,
-because after the call to @code{make-add} exits, the variable @code{n}
-is no longer bound to the actual argument 2.
+ Here is an example
+@iftex
+(see the next subsection, for how to actually enable lexical binding):
+@end iftex
+@ifnottex
+(@pxref{Using Lexical Binding}, for how to actually enable lexical binding):
+@end ifnottex
@example
-(defun make-add (n)
- (function (lambda (m) (+ n m)))) ; @r{Return a function.}
- @result{} make-add
-(fset 'add2 (make-add 2)) ; @r{Define function @code{add2}}
- ; @r{with @code{(make-add 2)}.}
- @result{} (lambda (m) (+ n m))
-(add2 4) ; @r{Try to add 2 to 4.}
-@error{} Symbol's value as variable is void: n
-@end example
+@group
+(let ((x 1)) ; @r{@code{x} is lexically bound.}
+ (+ x 3))
+ @result{} 4
-@cindex closures not available
- Some Lisp dialects have ``closures,'' objects that are like functions
-but record additional variable bindings. Emacs Lisp does not have
-closures.
+(defun getx ()
+ x) ; @r{@code{x} is used ``free'' in this function.}
-@node Impl of Scope
-@subsection Implementation of Dynamic Scoping
-@cindex deep binding
+(let ((x 1)) ; @r{@code{x} is lexically bound.}
+ (getx))
+@error{} Symbol's value as variable is void: x
+@end group
+@end example
- A simple sample implementation (which is not how Emacs Lisp actually
-works) may help you understand dynamic binding. This technique is
-called @dfn{deep binding} and was used in early Lisp systems.
+@noindent
+Here, the variable @code{x} has no global value. When it is lexically
+bound within a @code{let} form, it can be used in the textual confines
+of that @code{let} form. But it can @emph{not} be used from within a
+@code{getx} function called from the @code{let} form, since the
+function definition of @code{getx} occurs outside the @code{let} form
+itself.
+
+@cindex lexical environment
+ Here is how lexical binding works. Each binding construct defines a
+@dfn{lexical environment}, specifying the symbols that are bound
+within the construct and their local values. When the Lisp evaluator
+wants the current value of a variable, it looks first in the lexical
+environment; if the variable is not specified in there, it looks in
+the symbol's value cell, where the dynamic value is stored.
+
+@cindex closures
+ Lexical bindings have indefinite extent. Even after a binding
+construct has finished executing, its lexical environment can be
+``kept around'' in Lisp objects called @dfn{closures}. A closure is
+created when you create a named or anonymous function with lexical
+binding enabled. @xref{Closures}, for details.
+
+ When a closure is called as a function, any lexical variable
+references within its definition use the retained lexical environment.
+Here is an example:
- Suppose there is a stack of bindings, which are variable-value pairs.
-At entry to a function or to a @code{let} form, we can push bindings
-onto the stack for the arguments or local variables created there. We
-can pop those bindings from the stack at exit from the binding
-construct.
+@example
+(defvar my-ticker nil) ; @r{We will use this dynamically bound}
+ ; @r{variable to store a closure.}
- We can find the value of a variable by searching the stack from top to
-bottom for a binding for that variable; the value from that binding is
-the value of the variable. To set the variable, we search for the
-current binding, then store the new value into that binding.
-
- As you can see, a function's bindings remain in effect as long as it
-continues execution, even during its calls to other functions. That is
-why we say the extent of the binding is dynamic. And any other function
-can refer to the bindings, if it uses the same variables while the
-bindings are in effect. That is why we say the scope is indefinite.
-
-@cindex shallow binding
- The actual implementation of variable scoping in GNU Emacs Lisp uses a
-technique called @dfn{shallow binding}. Each variable has a standard
-place in which its current value is always found---the value cell of the
-symbol.
-
- In shallow binding, setting the variable works by storing a value in
-the value cell. Creating a new binding works by pushing the old value
-(belonging to a previous binding) onto a stack, and storing the new
-local value in the value cell. Eliminating a binding works by popping
-the old value off the stack, into the value cell.
-
- We use shallow binding because it has the same results as deep
-binding, but runs faster, since there is never a need to search for a
-binding.
+(let ((x 0)) ; @r{@code{x} is lexically bound.}
+ (setq my-ticker (lambda ()
+ (setq x (1+ x)))))
+ @result{} (closure ((x . 0) t) ()
+ (1+ x))
-@node Using Scoping
-@subsection Proper Use of Dynamic Scoping
+(funcall my-ticker)
+ @result{} 1
- Binding a variable in one function and using it in another is a
-powerful technique, but if used without restraint, it can make programs
-hard to understand. There are two clean ways to use this technique:
+(funcall my-ticker)
+ @result{} 2
-@itemize @bullet
-@item
-Use or bind the variable only in a few related functions, written close
-together in one file. Such a variable is used for communication within
-one program.
+(funcall my-ticker)
+ @result{} 3
-You should write comments to inform other programmers that they can see
-all uses of the variable before them, and to advise them not to add uses
-elsewhere.
+x ; @r{Note that @code{x} has no global value.}
+@error{} Symbol's value as variable is void: x
+@end example
-@item
-Give the variable a well-defined, documented meaning, and make all
-appropriate functions refer to it (but not bind it or set it) wherever
-that meaning is relevant. For example, the variable
-@code{case-fold-search} is defined as ``non-@code{nil} means ignore case
-when searching''; various search and replace functions refer to it
-directly or through their subroutines, but do not bind or set it.
-
-Then you can bind the variable in other programs, knowing reliably what
-the effect will be.
-@end itemize
+@noindent
+The @code{let} binding defines a lexical environment in which the
+variable @code{x} is locally bound to 0. Within this binding
+construct, we define a lambda expression which increments @code{x} by
+one and returns the incremented value. This lambda expression is
+automatically turned into a closure, in which the lexical environment
+lives on even after the @code{let} binding construct has exited. Each
+time we evaluate the closure, it increments @code{x}, using the
+binding of @code{x} in that lexical environment.
+
+ Note that functions like @code{symbol-value}, @code{boundp}, and
+@code{set} only retrieve or modify a variable's dynamic binding
+(i.e.@: the contents of its symbol's value cell). Also, the code in
+the body of a @code{defun} or @code{defmacro} cannot refer to
+surrounding lexical variables.
+
+ Currently, lexical binding is not much used within the Emacs
+sources. However, we expect its importance to increase in the future.
+Lexical binding opens up a lot more opportunities for optimization, so
+Emacs Lisp code that makes use of lexical binding is likely to run
+faster in future Emacs versions. Such code is also much more friendly
+to concurrency, which we want to add to Emacs in the near future.
+
+@node Using Lexical Binding
+@subsection Using Lexical Binding
+
+ When loading an Emacs Lisp file or evaluating a Lisp buffer, lexical
+binding is enabled if the buffer-local variable @code{lexical-binding}
+is non-@code{nil}:
+
+@defvar lexical-binding
+If this buffer-local variable is non-@code{nil}, Emacs Lisp files and
+buffers are evaluated using lexical binding instead of dynamic
+binding. (However, special variables are still dynamically bound; see
+below.) If @code{nil}, dynamic binding is used for all local
+variables. This variable is typically set for a whole Emacs Lisp
+file, as a file local variable (@pxref{File Local Variables}).
+Note that unlike other such variables, this one must be set in the
+first line of a file.
+@end defvar
+
+@noindent
+When evaluating Emacs Lisp code directly using an @code{eval} call,
+lexical binding is enabled if the @var{lexical} argument to
+@code{eval} is non-@code{nil}. @xref{Eval}.
+
+@cindex special variables
+ Even when lexical binding is enabled, certain variables will
+continue to be dynamically bound. These are called @dfn{special
+variables}. Every variable that has been defined with @code{defvar},
+@code{defcustom} or @code{defconst} is a special variable
+(@pxref{Defining Variables}). All other variables are subject to
+lexical binding.
+
+@defun special-variable-p SYMBOL
+This function returns non-@code{nil} if @var{symbol} is a special
+variable (i.e.@: it has a @code{defvar}, @code{defcustom}, or
+@code{defconst} variable definition). Otherwise, the return value is
+@code{nil}.
+@end defun
- In either case, you should define the variable with @code{defvar}.
-This helps other people understand your program by telling them to look
-for inter-function usage. It also avoids a warning from the byte
-compiler. Choose the variable's name to avoid name conflicts---don't
-use short names like @code{x}.
+ The use of a special variable as a formal argument in a function is
+discouraged. Doing so gives rise to unspecified behavior when lexical
+binding mode is enabled (it may use lexical binding sometimes, and
+dynamic binding other times).
+
+ Converting an Emacs Lisp program to lexical binding is pretty easy.
+First, add a file-local variable setting of @code{lexical-binding} to
+@code{t} in the Emacs Lisp source file. Second, check that every
+variable in the program which needs to be dynamically bound has a
+variable definition, so that it is not inadvertently bound lexically.
+
+ A simple way to find out which variables need a variable definition
+is to byte-compile the source file. @xref{Byte Compilation}. If a
+non-special variable is used outside of a @code{let} form, the
+byte-compiler will warn about reference or assignment to a ``free
+variable''. If a non-special variable is bound but not used within a
+@code{let} form, the byte-compiler will warn about an ``unused lexical
+variable''. The byte-compiler will also issue a warning if you use a
+special variable as a function argument.
+
+ (To silence byte-compiler warnings about unused variables, just use
+a variable name that start with an underscore. The byte-compiler
+interprets this as an indication that this is a variable known not to
+be used.)
@node Buffer-Local Variables
@section Buffer-Local Variables
@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
@end group
@end example
- Note that references to @code{foo} in @var{body} access the
+@noindent
+Note that references to @code{foo} in @var{body} access the
buffer-local binding of buffer @samp{b}.
When a file specifies local variable values, these become buffer-local
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
@defun buffer-local-variables &optional buffer
This function returns a list describing the buffer-local variables in
-buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is
-used.) It returns an association list (@pxref{Association Lists}) in
-which each element contains one buffer-local variable and its value.
-However, when a variable's buffer-local binding in @var{buffer} is void,
-then the variable appears directly in the resulting list.
+buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer
+is used.) Normally, each list element has the form
+@w{@code{(@var{sym} . @var{val})}}, where @var{sym} is a buffer-local
+variable (a symbol) and @var{val} is its buffer-local value. But when
+a variable's buffer-local binding in @var{buffer} is void, its list
+element is just @var{sym}.
@example
@group
@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
property value. Lambda expressions should be quoted so that
@code{describe-variable} can display the predicate.
+ When defining a user option using @code{defcustom}, you can set its
+@code{safe-local-variable} property by adding the arguments
+@code{:safe @var{function}} to @code{defcustom} (@pxref{Variable
+Definitions}).
+
@defopt safe-local-variable-values
This variable provides another way to mark some variable values as
safe. It is a list of cons cells @code{(@var{var} . @var{val})},
@end defun
@c @cindex risky local variable Duplicates risky-local-variable
- Some variables are considered @dfn{risky}. A variable whose name
-ends in any of @samp{-command}, @samp{-frame-alist}, @samp{-function},
+ Some variables are considered @dfn{risky}. If a variable is risky,
+it is never entered automatically into
+@code{safe-local-variable-values}; Emacs always queries before setting
+a risky variable, unless the user explicitly allows a value by
+customizing @code{safe-local-variable-values} directly.
+
+ Any variable whose name has a non-@code{nil}
+@code{risky-local-variable} property is considered risky. When you
+define a user option using @code{defcustom}, you can set its
+@code{risky-local-variable} property by adding the arguments
+@code{:risky @var{value}} to @code{defcustom} (@pxref{Variable
+Definitions}). In addition, any variable whose name ends in any of
+@samp{-command}, @samp{-frame-alist}, @samp{-function},
@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form},
@samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist},
-@samp{-program}, or @samp{-predicate} is considered risky. The
-variables @samp{font-lock-keywords}, @samp{font-lock-keywords}
-followed by a digit, and @samp{font-lock-syntactic-keywords} are also
-considered risky. Finally, any variable whose name has a
-non-@code{nil} @code{risky-local-variable} property is considered
-risky.
+@samp{-program}, or @samp{-predicate} is automatically considered
+risky. The variables @samp{font-lock-keywords},
+@samp{font-lock-keywords} followed by a digit, and
+@samp{font-lock-syntactic-keywords} are also considered risky.
@defun risky-local-variable-p sym
This function returns non-@code{nil} if @var{sym} is a risky variable,
based on the above criteria.
@end defun
- If a variable is risky, it will not be entered automatically into
-@code{safe-local-variable-values} as described above. Therefore,
-Emacs will always query before setting a risky variable, unless the
-user explicitly allows the setting by customizing
-@code{safe-local-variable-values} directly.
-
@defvar ignored-local-variables
This variable holds a list of variables that should not be given local
values by files. Any value specified for one of these variables is
@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
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
the old name is obsolete and therefore that it may be removed at some
stage in the future.
-@defun make-obsolete-variable obsolete-name current-name &optional when
+@defun make-obsolete-variable obsolete-name current-name when &optional access-type
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}
-is a string, this is the message and there is no replacement variable.
-
-If provided, @var{when} should be a string indicating when the
-variable was first made obsolete---for example, a date or a release
-number.
+@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} is a string, this is the message and there is no
+replacement variable. @var{when} should be a string indicating when
+the variable was first made obsolete (usually a version number
+string).
+
+The optional argument @var{access-type}, if non-@code{nil}, should
+should specify the kind of access that will trigger obsolescence
+warnings; it can be either @code{get} or @code{set}.
@end defun
You can make two variables synonyms and declare one obsolete at the
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