a function name. @xref{Symbol Components}.
The Lisp objects that constitute a Lisp program determine the textual
-form of the program--it is simply the read syntax for those Lisp
+form of the program---it is simply the read syntax for those Lisp
objects. This is why, for example, a variable in a textual Lisp program
is written using the read syntax for the symbol that represents the
variable.
* 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:: How to avoid bad results from quitting
+ within the code to initialize a variable.
* Accessing Variables:: Examining values of variables whose names
are known only at run time.
* Setting Variables:: Storing new values in variables.
local bindings.
@defspec let (bindings@dots{}) forms@dots{}
-This function binds variables according to @var{bindings} and then
+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}.
@end example
@end defspec
- Here is a complete list of the other facilities which create local
+ Here is a complete list of the other facilities that create local
bindings:
@itemize @bullet
@code{condition-case} (@pxref{Errors}).
@end itemize
+ Variables can also have buffer-local bindings (@pxref{Buffer-Local
+Variables}); a few variables have terminal-local bindings
+(@pxref{Multiple Displays}). 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.
+
@defvar max-specpdl-size
@cindex variable limit error
@cindex evaluation error
@node Defining Variables
@section Defining Global Variables
+@cindex variable definition
You may announce your intention to use a symbol as a global variable
-with a definition, using @code{defconst} or @code{defvar}.
+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
a matter of intent, serving to inform human readers of whether programs
will change the variable. Emacs Lisp does not restrict the ways in
which a variable can be used based on @code{defconst} or @code{defvar}
-declarations. However, it also makes a difference for initialization:
+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.
evaluates it and sets @var{symbol} to the result. (If @var{value} is
omitted, the value of @var{symbol} is not changed in any case.)
+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} evaluates it as a @code{defconst}. The purpose of
+this is to make sure the variable's value is reinitialized, when you ask
+for it specifically.
+
If @var{symbol} has a buffer-local binding in the current buffer,
@code{defvar} sets the default value, not the local value.
@xref{Buffer-Local Variables}.
(progn
(if (not (boundp '@var{symbol}))
(setq @var{symbol} @var{value}))
- (put '@var{symbol} 'variable-documentation '@var{doc-string})
+ (if '@var{doc-string}
+ (put '@var{symbol} 'variable-documentation '@var{doc-string}))
'@var{symbol})
@end group
@end example
@var{symbol} has a buffer-local binding in the current buffer,
@code{defconst} sets the default value, not the local value.
-@strong{Please note:} don't use @code{defconst} for user option
+@strong{Please note:} Don't use @code{defconst} for user option
variables in libraries that are not standardly preloaded. The user
should be able to specify a value for such a variable in the
@file{.emacs} file, so that it will be in effect if and when the library
@defun user-variable-p variable
@cindex user option
-This function returns @code{t} if @var{variable} is a user option--- a
+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.)
then the variable is a user option.
@end defun
+@kindex variable-interactive
If a user option variable has a @code{variable-interactive} property,
-@code{set-variable} uses that value to control reading the new value for
-the variable. The property's value is used as if it were the argument
-to @code{interactive}.
+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
+to @code{interactive} (@pxref{Using Interactive}).
- @strong{Warning:} if the @code{defconst} and @code{defvar} special
+ @strong{Warning:} If the @code{defconst} and @code{defvar} special
forms are used while the variable has a local binding, they set the
local binding's value; the global binding is not changed. This is not
what we really 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.
+@node Tips for Defining
+@section Tips for Defining Variables Robustly
+
+ 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
+entire computation of the value into the @code{defvar}, like this:
+
+@example
+(defvar my-mode-map
+ (let ((map (make-sparse-keymap)))
+ (define-key my-mode-map "\C-c\C-a" 'my-command)
+ @dots{}
+ map)
+ @var{docstring})
+@end example
+
+@noindent
+This method has several benefits. First, if the user quits while
+loading the file, the variable is either still uninitialized or
+initialized properly, never in-between. If it is 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.
+
+ 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
+variable. Here's a safe way to avoid that:
+
+@example
+(defvar my-mode-map nil
+ @var{docstring})
+(if my-mode-map
+ nil
+ (let ((map (make-sparse-keymap)))
+ (define-key my-mode-map "\C-c\C-a" 'my-command)
+ @dots{}
+ (setq my-mode-map map)))
+@end example
+
+@noindent
+This has all the same advantages as putting the initialization inside
+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})
+(if my-mode-map
+ nil
+ (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 only if the variable
+had been @code{ni}. 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
@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. If @var{symbol} is not
-actually a symbol, a @code{wrong-type-argument} error is signaled.
+set; shadowed bindings are not affected.
@example
@group
@end group
@end example
+If @var{symbol} is not actually a symbol, a @code{wrong-type-argument}
+error is signaled.
+
+@example
+(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 needed for choosing which
-variable to set is made at run time. For example, the command
+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
+@b{Common Lisp note:} In Common Lisp, @code{set} always changes the
symbol's special value, ignoring any lexical bindings. In Emacs Lisp,
all variables and all bindings are (in effect) special, so @code{set}
always affects the most local existing binding.
@end quotation
@end defun
+ One other function for setting a variable is designed to add
+an element to a list if it is not already present in the list.
+
+@defun add-to-list symbol element
+This function sets the variable @var{symbol} by consing @var{element}
+onto the old value, if @var{element} is not already a member of that
+value. It returns the resulting list, whether updated or not. The
+value of @var{symbol} had better be a list already before the call.
+
+The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
+is an ordinary function, like @code{set} and unlike @code{setq}. Quote
+the argument yourself if that is what you want.
+
+Here's a scenario showing how to use @code{add-to-list}:
+
+@example
+(setq foo '(a b))
+ @result{} (a b)
+
+(add-to-list 'foo 'c) ;; @r{Add @code{c}.}
+ @result{} (c a b)
+
+(add-to-list 'foo 'b) ;; @r{No effect.}
+ @result{} (c a b)
+
+foo ;; @r{@code{foo} was changed.}
+ @result{} (c a b)
+@end example
+@end defun
+
+ An equivalent expression for @code{(add-to-list '@var{var}
+@var{value})} is this:
+
+@example
+(or (member @var{value} @var{var})
+ (setq @var{var} (cons @var{value} @var{var})))
+@end example
+
@node Variable Scoping
@section Scoping Rules for Variable Bindings
@cindex CL note---special variables
@quotation
-@b{Common Lisp note:} variables declared ``special'' in Common Lisp
-are dynamically scoped like variables in Emacs Lisp.
+@b{Common Lisp note:} Variables declared ``special'' in Common Lisp
+are dynamically scoped, like variables in Emacs Lisp.
@end quotation
@menu
the effect will be.
@end itemize
+ 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}.
+
@node Buffer-Local Variables
@section Buffer-Local Variables
@cindex variables, buffer-local
kind of variable binding: @dfn{buffer-local} bindings, which apply only
to one buffer. Emacs Lisp is meant for programming editing commands,
and having different values for a variable in different buffers is an
-important customization method.
+important customization method. (A few variables have bindings that
+are local to a given X terminal; see @ref{Multiple Displays}.)
@menu
* Intro to Buffer-Local:: Introduction and concepts.
be changed with @code{setq}; you need to use @code{setq-default} to do
that.
- @strong{Warning:} when a variable has local values in one or more
+ @strong{Warning:} When a variable has local values in one or more
buffers, you can get Emacs very confused by binding the variable with
@code{let}, changing to a different current buffer in which a different
binding is in effect, and then exiting the @code{let}. This can
(setq foo 'a)
(let ((foo 'temp))
(set-buffer "b")
- @dots{})
+ @var{body}@dots{})
@group
foo @result{} 'a ; @r{The old buffer-local value from buffer @samp{a}}
; @r{is now the default value.}
buffer-local binding of buffer @samp{b}.
When a file specifies local variable values, these become buffer-local
-value when you visit the file. @xref{Auto Major Mode}.
+values when you visit the file. @xref{Auto Major Mode}.
@node Creating Buffer-Local
@subsection Creating and Deleting Buffer-Local Bindings
@result{} 5
@end group
@end example
+
+Making a variable buffer-local within a @code{let}-binding for that
+variable does not work. This is 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, this function signals an error. Such
+variables cannot have buffer-local bindings as well. @xref{Multiple
+Displays}.
+
+@strong{Note:} do not use @code{make-local-variable} for a hook
+variable. Instead, use @code{make-local-hook}. @xref{Hooks}.
@end deffn
@deffn Command make-variable-buffer-local variable
local to the current buffer at the time.
The value returned is @var{variable}.
+
+@strong{Note:} It is a mistake to use @code{make-variable-buffer-local}
+for user-option variables, simply because users @emph{might} want to
+customize them differently in different buffers. Users can make any
+variable local, when they wish to.
+
+The main use of @code{make-variable-buffer-local} is when a variable is
+used for internal purposes, and the Lisp program depends on having
+separate values in separate buffers.
@end deffn
+@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,
+@code{nil}.
+@end defun
+
@defun buffer-local-variables &optional buffer
This function returns a list describing the buffer-local variables in
buffer @var{buffer}. It returns an association list (@pxref{Association
create a local binding for it.
@code{kill-local-variable} returns @var{variable}.
+
+This function is a command because it is sometimes useful to kill one
+buffer-local variable interactively, just as it is useful to create
+buffer-local variables interactively.
@end deffn
@defun kill-all-local-variables
buffer has a buffer-local binding. For example, you could use
@code{setq-default} to change the default setting of
@code{paragraph-start} for most buffers; and this would work even when
-you are in a C or Lisp mode buffer which has a buffer-local value for
+you are in a C or Lisp mode buffer that has a buffer-local value for
this variable.
@c Emacs 19 feature
@end defun
@c Emacs 19 feature
-@defun default-boundp variable
-The function @code{default-boundp} tells you whether @var{variable}'s
+@defun default-boundp symbol
+The function @code{default-boundp} tells you whether @var{symbol}'s
default value is nonvoid. If @code{(default-boundp 'foo)} returns
@code{nil}, then @code{(default-value 'foo)} would get an error.
@end group
@end example
@end defun
-