@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2016 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Variables
@chapter Variables
@menu
* Global Variables:: Variable values that exist permanently, everywhere.
-* Constant Variables:: Certain "variables" have values that never change.
+* Constant Variables:: Variables 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.
@code{nil} otherwise.
@end defun
-These constants are fundamentally different from the ``constants''
+These constants are fundamentally different from the constants
defined using the @code{defconst} special form (@pxref{Defining
Variables}). A @code{defconst} form serves to inform human readers
that you do not intend to change the value of a variable, but Emacs
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
+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},
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.
+where you are in Emacs.
@defopt max-specpdl-size
@anchor{Definition of max-specpdl-size}
@end defopt
@node Void Variables
-@section When a Variable is ``Void''
+@section When a Variable is Void
@cindex @code{void-variable} error
@cindex void variable
@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 @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{value} is specified, and @var{symbol} is void (i.e., it has no
+dynamically bound value; @pxref{Void Variables}), then @var{value} is
+evaluated and @var{symbol} is set to the result. But if @var{symbol}
+is not void, @var{value} is not evaluated, and @var{symbol}'s value is
+left 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,
-not the current (buffer-local) binding. It sets the default value if
+@code{defvar} acts on the default value, which is buffer-independent,
+rather than the buffer-local binding. It sets the default value if
the default value is void. @xref{Buffer-Local Variables}.
+If @var{symbol} is already lexically bound (e.g., if the @code{defvar}
+form occurs in a @code{let} form with lexical binding enabled), then
+@code{defvar} sets the dynamic value. The lexical binding remains in
+effect until its binding construct exits. @xref{Variable Scoping}.
+
When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
Emacs Lisp mode (@code{eval-defun}), a special feature of
@code{eval-defun} arranges to set the variable unconditionally, without
@item @dots{}-predicate
The value is a predicate---a function of one argument that returns
-non-@code{nil} for ``good'' arguments and @code{nil} for ``bad''
-arguments.
+non-@code{nil} for success and @code{nil} for failure.
@item @dots{}-flag
The value is significant only as to whether it is @code{nil} or not.
@end table
When you define a variable, always consider whether you should mark
-it as ``safe'' or ``risky''; see @ref{File Local Variables}.
+it as safe or risky; see @ref{File Local Variables}.
When defining and initializing a variable that holds a complicated
value (such as a keymap with bindings in it), it's best to put the
@example
@group
-(defvar x -99) ; @r{@code{x} receives an initial value of -99.}
+(defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.}
(defun getx ()
- x) ; @r{@code{x} is used ``free'' in this function.}
+ 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.}
+;; @r{previous value, which is @minus{}99.}
(getx)
@result{} -99
@end example
@noindent
-The function @code{getx} refers to @code{x}. This is a ``free''
+The function @code{getx} refers to @code{x}. This is a @dfn{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 (i.e., 1). But when we call @code{getx}
outside the @code{let} form, it retrieves the global value (i.e.,
--99).
+@minus{}99).
Here is another example, which illustrates setting a dynamically
bound variable using @code{setq}:
@example
@group
-(defvar x -99) ; @r{@code{x} receives an initial value of -99.}
+(defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.}
(defun addx ()
(setq x (1+ x))) ; @r{Add 1 to @code{x} and return its new value.}
@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.}
+;; @r{previous value, which is @minus{}99.}
(addx)
@result{} -98
@result{} 4
(defun getx ()
- x) ; @r{@code{x} is used ``free'' in this function.}
+ x) ; @r{@code{x} is used free in this function.}
(let ((x 1)) ; @r{@code{x} is lexically bound.}
(getx))
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
+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
buffer-local variables interactively.
@end deffn
+@cindex local variables, killed by major mode
@defun kill-all-local-variables
This function eliminates all the buffer-local variable bindings of the
-current buffer except for variables marked as ``permanent'' and local
+current buffer except for variables marked as permanent and local
hook functions that have a non-@code{nil} @code{permanent-local-hook}
property (@pxref{Setting Hooks}). As a result, the buffer will see
the default values of most variables.
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}.
+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
@node Variables with Restricted Values
@section Variables with Restricted Values
+@cindex lisp variables defined in C, restrictions
Ordinary Lisp variables can be assigned any value that is a valid
Lisp object. However, certain Lisp variables are not defined in Lisp,
This variable holds a list of all variables of type @code{DEFVAR_BOOL}.
@end defvar
- Variables of type @code{DEFVAR_INT} can only take on integer values.
+ Variables of type @code{DEFVAR_INT} can take on only integer values.
Attempting to assign them any other value will result in an error:
@example
@node Generalized Variables
@section Generalized Variables
+@cindex generalized variable
+@cindex place form
A @dfn{generalized variable} or @dfn{place form} is one of the many places
in Lisp memory where values can be stored. The simplest place form is
a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements
of arrays, properties of symbols, and many other locations are also
places where Lisp values are stored.
-Generalized variables are analogous to ``lvalues'' in the C
+Generalized variables are analogous to lvalues in the C
language, where @samp{x = a[i]} gets an element from an array
and @samp{a[i] = x} stores an element using the same notation.
Just as certain forms like @code{a[i]} can be lvalues in C, there
A call to any of the following Emacs-specific functions:
@smallexample
-default-value process-get
+alist-get process-get
frame-parameter process-sentinel
terminal-parameter window-buffer
keymap-parent window-display-table
overlay-start window-parameter
overlay-end window-point
process-buffer window-start
-process-filter
+process-filter default-value
@end smallexample
@end itemize
@cindex CL note---no @code{setf} functions
@quotation
@b{Common Lisp note:} Common Lisp defines another way to specify the
-@code{setf} behavior of a function, namely ``@code{setf} functions'',
+@code{setf} behavior of a function, namely @code{setf} functions,
whose names are lists @code{(setf @var{name})} rather than symbols.
For example, @code{(defun (setf foo) @dots{})} defines the function
that is used when @code{setf} is applied to @code{foo}. Emacs does