@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2012 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.
In Lisp, each variable is represented by a Lisp symbol
-(@pxref{Symbols}). The symbol's name serves as the variable name, and
-the symbol's value cell holds the variable's value@footnote{Strictly
-speaking, the symbol's value cell always holds the variable's current
-value under the default @dfn{dynamic binding} rules. Under
-@dfn{lexical binding} rules, the value cell holds the variable's
-@dfn{global value}. @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.
+(@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
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 has a @dfn{local binding}, or that it is a @dfn{local
-variable}.
+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
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 local binding for
-that variable that still exists. For details about dynamic scoping,
-and an alternative scoping rule called @dfn{lexical scoping},
-@xref{Variable Scoping}.
+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:
@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}. Note that this
-does @emph{not} mean the value is @code{nil}. 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.
-
- More precisely, a variable is void if its symbol has an unassigned
-value cell (@pxref{Symbol Components}). Under Emacs Lisp's default
-dynamic binding rules, the value cell stores the variable's current
-(local or global) value; if a variable is void, trying to evaluate the
-variable signals a @code{void-variable} error rather than a value.
-But when a variable is lexically bound, it can have a local value
-which is determined by the lexical environment, even if the value cell
-is empty and the variable is technically void. @xref{Variable
-Scoping}.
+ 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 empties out the value cell of @var{symbol}, making the
variable void. It returns @var{symbol}.
-If @var{symbol} has a (dynamic) local binding, @code{makunbound} voids
+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,
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,
function to extract the value.
@defun symbol-value symbol
-This function returns the value of @var{symbol}. This is the value in
-the symbol's value cell, which is where the variable's current
-(dynamic) value is stored. If the variable has no local binding, this
-is simply its global value.
+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 the dynamic value, and not the local lexical
-value (which is determined by the lexical environment rather than the
-symbol's value cell). @xref{Variable Scoping}.
+@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 @var{symbol} is void as a
-variable.
@end defun
@node Setting Variables
@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}.
@example
@group
-(defun getx ()
- x) ; @r{@code{x} is used ``free'' in this function.}
-
(let ((x 1)) ; @r{@code{x} is lexically bound.}
(+ x 3))
@result{} 4
+(defun getx ()
+ x) ; @r{@code{x} is used ``free'' in this function.}
+
(let ((x 1)) ; @r{@code{x} is lexically bound.}
(getx))
@error{} Symbol's value as variable is void: x
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 dynamical value is stored.
+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 whenever you evaluate a lambda expression (@pxref{Lambda
-Expressions}) with lexical binding enabled. It is represented by a
-list whose @sc{car} is the symbol @code{closure}. It is a function,
-in the sense that it can be passed as an argument to @code{funcall};
-when called as a function, any lexical variable references within its
-definition will use the retained lexical environment.
+created when you create a named or anonymous function with lexical
+binding enabled. @xref{Closures}, for details.
- Here is an example which illustrates the use of a closure:
+ When a closure is called as a function, any lexical variable
+references within its definition use the retained lexical environment.
+Here is an example:
@example
(defvar my-ticker nil) ; @r{We will use this dynamically bound}
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
@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
@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
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
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
HCoop / bpt / emacs.git / blobdiff