Commit 1021c761 authored by Chong Yidong's avatar Chong Yidong
Browse files

Update Variables chapter of Lisp manual to handle lexical binding.

* doc/lispref/variables.texi (Variables, Local Variables, Void Variables):
Edit to make the descriptions less specific to dynamic binding.
(Local Variables): Default max-specpdl-size is now 1300.
(Defining Variables): Edits for lexical scoping.  Delete
information about starting docstrings with *.  De-document
user-variable-p.
(Tips for Defining): Remove an unimportant discussion of quitting
in the middle of a load.
(Accessing Variables, Setting Variables): Discuss lexical binding.
(Variable Scoping): Rewrite.
(Scope, Extent, Impl of Scope): Nodes deleted.
(Dynamic Binding): New node, with material from Scope, Extent, and
Impl of Scope nodes.
(Dynamic Binding Tips): Rename from Using Scoping.
(Lexical Binding): Rewrite.
(Using Lexical Binding): Rename from Converting to Lexical
Binding.  Convert to subsection.

* doc/lispref/customize.texi (Variable Definitions): Add custom-variable-p.
Move user-variable-p documentation here.
parent 6725d21a
2012-01-24 Chong Yidong <cyd@gnu.org>
* variables.texi (Variables, Local Variables, Void Variables):
Edit to make the descriptions less specific to dynamic binding.
(Local Variables): Default max-specpdl-size is now 1300.
(Defining Variables): Edits for lexical scoping. Delete
information about starting docstrings with *. De-document
user-variable-p.
(Tips for Defining): Remove an unimportant discussion of quitting
in the middle of a load.
(Accessing Variables, Setting Variables): Discuss lexical binding.
(Variable Scoping): Rewrite.
(Scope, Extent, Impl of Scope): Nodes deleted.
(Dynamic Binding): New node, with material from Scope, Extent, and
Impl of Scope nodes.
(Dynamic Binding Tips): Rename from Using Scoping.
(Lexical Binding): Rewrite.
(Using Lexical Binding): Rename from Converting to Lexical
Binding. Convert to subsection.
* customize.texi (Variable Definitions): Add custom-variable-p.
Move user-variable-p documentation here.
2012-01-23 Chong Yidong <cyd@gnu.org>
* strings.texi (Text Comparison): Minor qualification.
......
......@@ -262,12 +262,6 @@ turn this feature back on, if someone would like to do the work.
This macro declares @var{option} as a customizable @dfn{user option}.
You should not quote @var{option}.
This causes the function @code{user-variable-p} to return @code{t}
when given @var{option} as an argument. @xref{Defining Variables}.
The argument @var{doc} specifies the documentation string for the
variable. (Note that there is no need to start @var{doc} with a
@samp{*}.)
The argument @var{standard} is an expression that specifies the
standard value for @var{option}. Evaluating the @code{defcustom} form
evaluates @var{standard}, but does not necessarily install the
......@@ -285,6 +279,9 @@ evaluate at any time. We recommend avoiding backquotes in
@var{standard}, because they are not expanded when editing the value,
so list values will appear to have the wrong structure.
The argument @var{doc} specifies the documentation string for the
variable.
Every @code{defcustom} should specify @code{:group} at least once.
If you specify the @code{:set} keyword, to make the variable take other
......@@ -474,6 +471,22 @@ A good place to put calls to this function is in the function
or in the various hooks it calls.
@end defun
@defun custom-variable-p arg
This function returns non-@code{nil} if @var{arg} is a customizable
variable. A customizable variable is either a variable that has a
@code{standard-value} or @code{custom-autoload} property (usually
meaning it was declared with @code{defcustom}), or an alias for
another customizable variable.
@end defun
@defun user-variable-p arg
This function is like @code{custom-variable-p}, except it also returns
@code{t} if the first character of the variable's documentation string
is the character @samp{*}. That is an obsolete way of indicating a
user option, so for most purposes you may consider
@code{user-variable-p} as equivalent to @code{custom-variable-p}.
@end defun
@node Customization Types
@section Customization Types
......
......@@ -436,12 +436,10 @@ Variables
Scoping Rules for Variable Bindings
* 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.
Buffer-Local Variables
......
......@@ -1795,6 +1795,9 @@ with references to further information.
@item consp
@xref{List-related Predicates, consp}.
@item custom-variable-p
@xref{Variable Definitions, custom-variable-p}.
@item display-table-p
@xref{Display Tables, display-table-p}.
......@@ -1870,9 +1873,6 @@ with references to further information.
@item syntax-table-p
@xref{Syntax Tables, syntax-table-p}.
@item user-variable-p
@xref{Defining Variables, user-variable-p}.
@item vectorp
@xref{Vectors, vectorp}.
......
......@@ -8,20 +8,23 @@
@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 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.
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
......@@ -145,63 +148,63 @@ does not raise an error if you actually change it.
@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 has a @dfn{local binding}, or 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 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}.
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.
......@@ -213,6 +216,7 @@ Here is an example of this: @code{z} is bound to the old value of
(setq y 2)
@result{} 2
@end group
@group
(let ((y 1)
(z y))
......@@ -226,15 +230,15 @@ Here is an example of this: @code{z} is bound to the old value of
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}.}
......@@ -262,7 +266,7 @@ Macro calls (@pxref{Macros}).
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}
......@@ -280,7 +284,7 @@ that Lisp avoids infinite recursion on an ill-defined function.
@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
......@@ -291,45 +295,32 @@ has room to execute.
@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}.
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}.
@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
......@@ -361,17 +352,11 @@ x ; @r{The global binding is unchanged.}
@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
......@@ -402,52 +387,41 @@ more precisely, if its current binding is not void. It returns
@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. It also declares this variable as @dfn{special}, meaning that it
should always use dynamic scoping rules. 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; instead, the only effect of @code{defvar} is to declare locally that this
variable exists elsewhere and should hence always use dynamic scoping rules.
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,
......@@ -459,19 +433,9 @@ Emacs Lisp mode (@code{eval-defun}), a special feature of
@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:
......@@ -494,38 +458,6 @@ it a documentation string:
@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
......@@ -538,6 +470,11 @@ global value, established here, that should not be changed by the user
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,
......@@ -567,37 +504,13 @@ float-pi
@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
@cindex @code{variable-interactive} property
@findex set-variable
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
......@@ -667,9 +580,9 @@ loading the file, the variable is either still uninitialized or
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
......@@ -690,37 +603,27 @@ 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})
(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.
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.