@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-2015 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Variables
@chapter Variables
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
+be precise, under the default @dfn{dynamic scoping} rule, 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
+case under the @dfn{lexical scoping} rule. @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
* 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.
+* Generalized Variables:: Extending the concept of variables.
@end menu
@node Global Variables
of one) comes back.
@cindex current binding
- A variable can have more than one local binding at a time (e.g.@: if
+ 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,
@cindex void variable
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.
+cell (@pxref{Symbol Components}).
+
+ Under Emacs Lisp's default dynamic scoping rule (@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, instead
+of returning a value.
+
+ Under the optional lexical scoping rule, the value cell only holds
+the variable's global value---the value outside of any lexical binding
+construct. When a variable is lexically bound, the local value is
+determined by the lexical environment; hence, variables can have local
+values even if their symbols' value cells are unassigned.
@defun makunbound symbol
This function empties out the value cell of @var{symbol}, making the
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}.
+(which calls @code{defvar} as a subroutine). @xref{Variable
+Definitions}.
@defspec defvar symbol [value [doc-string]]
This special form defines @var{symbol} as a variable. Note that
@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
@node Variable Scoping
@section Scoping Rules for Variable Bindings
+@cindex scoping rule
When you create a local binding for a variable, that binding takes
effect only within a limited portion of the program (@pxref{Local
program is executing, the binding exists.
@cindex dynamic binding
-@cindex indefinite scope
+@cindex dynamic 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
+bindings}. Such a binding has @dfn{dynamic 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 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}.
+variable must be located textually within the binding
+construct@footnote{With some exceptions; for instance, a lexical
+binding can also be accessed from the Lisp debugger.}. 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
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:
+ Dynamic bindings have dynamic scope and extent, as shown by the
+following example:
@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.}
@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
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).
+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.,
+@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
@itemize @bullet
@item
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.
+only within a binding construct, such as the body of the @code{let}
+form where the variable was bound. 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
Otherwise, define the variable with @code{defvar}, @code{defconst}, or
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}
+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}.
@node Lexical Binding
@subsection Lexical Binding
-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.
+ Lexical binding was introduced to Emacs, as an optional feature, in
+version 24.1. We expect its importance to increase in the future.
+Lexical binding opens up many more opportunities for optimization, so
+programs using it are likely to run faster in future Emacs versions.
+Lexical binding is also more compatible with concurrency, which we
+want to add to Emacs in the future.
- Here is an example
+ A lexically-bound variable has @dfn{lexical scope}, meaning that any
+reference to the variable must be located textually within the binding
+construct. Here is an example
@iftex
(see the next subsection, for how to actually enable lexical binding):
@end iftex
environment; if the variable is not specified in there, it looks in
the symbol's value cell, where the dynamic value is stored.
+ (Internally, the lexical environment is an alist of symbol-value
+pairs, with the final element in the alist being the symbol @code{t}
+rather than a cons cell. Such an alist can be passed as the second
+argument to the @code{eval} function, in order to specify a lexical
+environment in which to evaluate a form. @xref{Eval}. Most Emacs
+Lisp programs, however, should not interact directly with lexical
+environments in this way; only specialized programs like debuggers.)
+
@cindex closures, example of using
Lexical bindings have indefinite extent. Even after a binding
construct has finished executing, its lexical environment can be
(setq my-ticker (lambda ()
(setq x (1+ x)))))
@result{} (closure ((x . 0) t) ()
- (1+ x))
+ (setq x (1+ x)))
(funcall my-ticker)
@result{} 1
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
+(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
(@pxref{Defining Variables}). All other variables are subject to
lexical binding.
-@defun special-variable-p SYMBOL
+@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
+variable (i.e., it has a @code{defvar}, @code{defcustom}, or
@code{defconst} variable definition). Otherwise, the return value is
@code{nil}.
@end defun
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.
+ Converting an Emacs Lisp program to lexical binding is easy. First,
+add a file-local variable setting of @code{lexical-binding} to
+@code{t} in the header line of the Emacs Lisp source file (@pxref{File
+Local Variables}). 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.
+@cindex free variable
+@cindex unused lexical variable
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
@code{remove-hook}.
@end deffn
+@defmac setq-local variable value
+This macro creates a buffer-local binding in the current buffer for
+@var{variable}, and gives it the buffer-local value @var{value}. It
+is equivalent to calling @code{make-local-variable} followed by
+@code{setq}. @var{variable} should be an unquoted symbol.
+@end defmac
+
@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
@code{make-variable-buffer-local} can be the best solution.
@end deffn
+@defmac defvar-local variable value &optional docstring
+This macro defines @var{variable} as a variable with initial value
+@var{value} and @var{docstring}, and marks it as automatically
+buffer-local. It is equivalent to calling @code{defvar} followed by
+@code{make-variable-buffer-local}. @var{variable} should be an
+unquoted symbol.
+@end defmac
+
@defun local-variable-p variable &optional buffer
This returns @code{t} if @var{variable} is buffer-local in buffer
@var{buffer} (which defaults to the current buffer); otherwise,
@end defun
@defun local-variable-if-set-p variable &optional buffer
-This returns @code{t} if @var{variable} will become buffer-local in
-buffer @var{buffer} (which defaults to the current buffer) if it is
-set there.
+This returns @code{t} if @var{variable} either has a buffer-local
+value in buffer @var{buffer}, or is automatically buffer-local.
+Otherwise, it returns @code{nil}. If omitted or @code{nil},
+@var{buffer} defaults to the current buffer.
@end defun
@defun buffer-local-value variable buffer
subsequent major mode. @xref{Hooks}.
@end defvar
-@c Emacs 19 feature
@cindex permanent local variable
A buffer-local variable is @dfn{permanent} if the variable name (a
symbol) has a @code{permanent-local} property that is non-@code{nil}.
A file can specify local variable values; Emacs uses these to create
buffer-local bindings for those variables in the buffer visiting that
-file. @xref{File variables, , Local Variables in Files, emacs, The
+file. @xref{File Variables, , Local Variables in Files, emacs, The
GNU Emacs Manual}, for basic information about file-local variables.
This section describes the functions and variables that affect how
file-local variables are processed.
variables have @code{safe-local-variable} properties; these include
@code{fill-column}, @code{fill-prefix}, and @code{indent-tabs-mode}.
For boolean-valued variables that are safe, use @code{booleanp} as the
-property value. Lambda expressions should be quoted so that
-@code{describe-variable} can display the predicate.
+property value.
When defining a user option using @code{defcustom}, you can set its
@code{safe-local-variable} property by adding the arguments
updates this list.
@end defvar
+@defvar enable-dir-local-variables
+If @code{nil}, directory-local variables are ignored. This variable
+may be useful for modes that want to ignore directory-locals while
+still respecting file-local variables (@pxref{File Local Variables}).
+@end defvar
+
@node Variable Aliases
@section Variable Aliases
@cindex variable aliases
+@cindex alias, for variables
It is sometimes useful to make two variables synonyms, so that both
variables always have the same value, and changing either one also
@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,
-but in C. Most of these variables are defined in the C code using
+but in C@. Most of these variables are defined in the C code using
@code{DEFVAR_LISP}. Like variables defined in Lisp, these can take on
any value. However, some variables are defined using
@code{DEFVAR_INT} or @code{DEFVAR_BOOL}. @xref{Defining 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
(setq undo-limit 1000.0)
@error{} Wrong type argument: integerp, 1000.0
@end 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
+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
+is a set of forms that can be generalized variables in Lisp.
+
+@menu
+* Setting Generalized Variables:: The @code{setf} macro.
+* Adding Generalized Variables:: Defining new @code{setf} forms.
+@end menu
+
+@node Setting Generalized Variables
+@subsection The @code{setf} Macro
+
+The @code{setf} macro is the most basic way to operate on generalized
+variables. The @code{setf} form is like @code{setq}, except that it
+accepts arbitrary place forms on the left side rather than just
+symbols. For example, @code{(setf (car a) b)} sets the car of
+@code{a} to @code{b}, doing the same operation as @code{(setcar a b)},
+but without having to remember two separate functions for setting and
+accessing every type of place.
+
+@defmac setf [place form]@dots{}
+This macro evaluates @var{form} and stores it in @var{place}, which
+must be a valid generalized variable form. If there are several
+@var{place} and @var{form} pairs, the assignments are done sequentially
+just as with @code{setq}. @code{setf} returns the value of the last
+@var{form}.
+@end defmac
+
+The following Lisp forms will work as generalized variables, and
+so may appear in the @var{place} argument of @code{setf}:
+
+@itemize
+@item
+A symbol naming a variable. In other words, @code{(setf x y)} is
+exactly equivalent to @code{(setq x y)}, and @code{setq} itself is
+strictly speaking redundant given that @code{setf} exists. Many
+programmers continue to prefer @code{setq} for setting simple
+variables, though, purely for stylistic or historical reasons.
+The macro @code{(setf x y)} actually expands to @code{(setq x y)},
+so there is no performance penalty for using it in compiled code.
+
+@item
+A call to any of the following standard Lisp functions:
+
+@smallexample
+aref cddr symbol-function
+car elt symbol-plist
+caar get symbol-value
+cadr gethash
+cdr nth
+cdar nthcdr
+@end smallexample
+
+@item
+A call to any of the following Emacs-specific functions:
+
+@smallexample
+default-value process-get
+frame-parameter process-sentinel
+terminal-parameter window-buffer
+keymap-parent window-display-table
+match-data window-dedicated-p
+overlay-get window-hscroll
+overlay-start window-parameter
+overlay-end window-point
+process-buffer window-start
+process-filter
+@end smallexample
+@end itemize
+
+@noindent
+@code{setf} signals an error if you pass a @var{place} form that it
+does not know how to handle.
+
+@c And for cl-lib's cl-getf.
+Note that for @code{nthcdr}, the list argument of the function must
+itself be a valid @var{place} form. For example, @code{(setf (nthcdr
+0 foo) 7)} will set @code{foo} itself to 7.
+@c The use of @code{nthcdr} as a @var{place} form is an extension
+@c to standard Common Lisp.
+
+@c FIXME I don't think is a particularly good way to do it,
+@c but these macros are introduced before generalized variables are.
+The macros @code{push} (@pxref{List Variables}) and @code{pop}
+(@pxref{List Elements}) can manipulate generalized variables,
+not just lists. @code{(pop @var{place})} removes and returns the first
+element of the list stored in @var{place}. It is analogous to
+@code{(prog1 (car @var{place}) (setf @var{place} (cdr @var{place})))},
+except that it takes care to evaluate all subforms only once.
+@code{(push @var{x} @var{place})} inserts @var{x} at the front of
+the list stored in @var{place}. It is analogous to @code{(setf
+@var{place} (cons @var{x} @var{place}))}, except for evaluation of the
+subforms. Note that @code{push} and @code{pop} on an @code{nthcdr}
+place can be used to insert or delete at any position in a list.
+
+The @file{cl-lib} library defines various extensions for generalized
+variables, including additional @code{setf} places.
+@xref{Generalized Variables,,, cl, Common Lisp Extensions}.
+
+
+@node Adding Generalized Variables
+@subsection Defining new @code{setf} forms
+
+This section describes how to define new forms that @code{setf} can
+operate on.
+
+@defmac gv-define-simple-setter name setter &optional fix-return
+This macro enables you to easily define @code{setf} methods for simple
+cases. @var{name} is the name of a function, macro, or special form.
+You can use this macro whenever @var{name} has a directly
+corresponding @var{setter} function that updates it, e.g.,
+@code{(gv-define-simple-setter car setcar)}.
+
+This macro translates a call of the form
+
+@example
+(setf (@var{name} @var{args}@dots{}) @var{value})
+@end example
+
+into
+@example
+(@var{setter} @var{args}@dots{} @var{value})
+@end example
+
+@noindent
+Such a @code{setf} call is documented to return @var{value}. This is
+no problem with, e.g., @code{car} and @code{setcar}, because
+@code{setcar} returns the value that it set. If your @var{setter}
+function does not return @var{value}, use a non-@code{nil} value for
+the @var{fix-return} argument of @code{gv-define-simple-setter}. This
+expands into something equivalent to
+@example
+(let ((temp @var{value}))
+ (@var{setter} @var{args}@dots{} temp)
+ temp)
+@end example
+so ensuring that it returns the correct result.
+@end defmac
+
+
+@defmac gv-define-setter name arglist &rest body
+This macro allows for more complex @code{setf} expansions than the
+previous form. You may need to use this form, for example, if there
+is no simple setter function to call, or if there is one but it
+requires different arguments to the place form.
+
+This macro expands the form
+@code{(setf (@var{name} @var{args}@dots{}) @var{value})} by
+first binding the @code{setf} argument forms
+@code{(@var{value} @var{args}@dots{})} according to @var{arglist},
+and then executing @var{body}. @var{body} should return a Lisp
+form that does the assignment, and finally returns the value that was
+set. An example of using this macro is:
+
+@example
+(gv-define-setter caar (val x) `(setcar (car ,x) ,val))
+@end example
+@end defmac
+
+@findex gv-define-expander
+@findex gv-letplace
+@c FIXME? Not sure what or how much to say about these.
+@c See cl.texi for an example of using gv-letplace.
+For more control over the expansion, see the macro @code{gv-define-expander}.
+The macro @code{gv-letplace} can be useful in defining macros that
+perform similarly to @code{setf}; for example, the @code{incf} macro
+of Common Lisp. Consult the source file @file{gv.el} for more details.
+
+@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'',
+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
+not support this. It is a compile-time error to use @code{setf} on a
+form that has not already had an appropriate expansion defined. In
+Common Lisp, this is not an error since the function @code{(setf
+@var{func})} might be defined later.
+@end quotation