Next: Accessing Variables, Previous: Void Variables, Up: Variables [Contents][Index]
You may announce your intention to use a symbol as a global variable
with a variable definition: a special form, either defconst
or defvar.
In SXEmacs Lisp, definitions serve three purposes. First, they inform
people who read the code that certain symbols are 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 etags and
make-docfile, which create data bases of the functions and
variables in a program.
The difference between defconst and defvar is primarily
a matter of intent, serving to inform human readers of whether programs
will change the variable. SXEmacs Lisp does not restrict the ways in
which a variable can be used based on defconst or defvar
declarations. However, it does make a difference for initialization:
defconst unconditionally initializes the variable, while
defvar initializes it only if it is void.
One would expect user option variables to be defined with
defconst, since programs do not change them. Unfortunately, this
has bad results if the definition is in a library that is not preloaded:
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 defvar.
This special form defines symbol as a value and initializes it.
The definition informs a person reading your code that symbol is
used as a variable that programs are likely to set or change. It is
also used for all user option variables except in the preloaded parts of
XEmacs. Note that symbol is not evaluated; the symbol to be
defined must appear explicitly in the defvar.
If symbol already has a value (i.e., it is not void), value
is not even evaluated, and symbol’s value remains unchanged. If
symbol is void and value is specified, defvar
evaluates it and sets symbol to the result. (If value is
omitted, the value of symbol is not changed in any case.)
When you evaluate a top-level defvar form with C-M-x in
Emacs Lisp mode (eval-defun), a special feature of
eval-defun evaluates it as a defconst. The purpose of
this is to make sure the variable’s value is reinitialized, when you ask
for it specifically.
If symbol has a buffer-local binding in the current buffer,
defvar sets the default value, not the local value.
See Buffer-Local Variables.
If the 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 variable-documentation property. The
SXEmacs help functions (see Documentation) look for this property.
If the first character of doc-string is ‘*’, it means that
this variable is considered a user option. This lets users set the
variable conveniently using the commands set-variable and
edit-options.
For example, this form defines foo but does not set its value:
(defvar foo)
⇒ foo
The following example sets the value of bar to 23, and
gives it a documentation string:
(defvar bar 23
"The normal weight of a bar.")
⇒ bar
The following form changes the documentation string for bar,
making it a user option, but does not change the value, since bar
already has a value. (The addition (1+ 23) is not even
performed.)
(defvar bar (1+ 23)
"*The normal weight of a bar.")
⇒ bar
bar
⇒ 23
Here is an equivalent expression for the defvar special form:
(defvar symbol value doc-string)
≡
(progn
(if (not (boundp 'symbol))
(setq symbol value))
(put 'symbol 'variable-documentation 'doc-string)
'symbol)
The defvar form returns symbol, but it is normally used
at top level in a file where its value does not matter.
This special form defines symbol as a value and initializes it.
It informs a person reading your code that symbol has a global
value, established here, that will not normally be changed or locally
bound by the execution of the program. The user, however, may be
welcome to change it. Note that symbol is not evaluated; the
symbol to be defined must appear explicitly in the defconst.
defconst always evaluates value and sets the global value
of symbol to the result, provided value is given. If
symbol has a buffer-local binding in the current buffer,
defconst sets the default value, not the local value.
Please note: Don’t use 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
.emacs file, so that it will be in effect if and when the library
is loaded later.
Here, pi is a constant that presumably ought not to be changed
by anyone (attempts by the Indiana State Legislature notwithstanding).
As the second form illustrates, however, this is only advisory.
(defconst pi 3.1415 "Pi to five places.")
⇒ pi
(setq pi 3)
⇒ pi
pi
⇒ 3
This function returns t if variable is a user option—a
variable intended to be set by the user for customization—and
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 by the
first character of the variable-documentation property. If the
property exists and is a string, and its first character is ‘*’,
then the variable is a user option.
If a user option variable has a variable-interactive property,
the 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
the argument to interactive.
Warning: If the defconst and 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.
Next: Accessing Variables, Previous: Void Variables, Up: Variables [Contents][Index]