Next: Tips for Defining, Previous: Void Variables, Up: Variables
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 Emacs 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 the value
should ever change. Emacs 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.
This special form defines symbol as a variable and can also initialize and document it. The definition informs a person reading your code that symbol is used as a variable that might be set or changed. Note that symbol is not evaluated; the symbol to be defined must appear explicitly in the
defvar
.If symbol is void and value is specified,
defvar
evaluates it and sets symbol to the result. But if symbol already has a value (i.e., it is not void), value is not even evaluated, and symbol's value remains unchanged. If value is omitted, the value of symbol is not changed in any case.If symbol has a buffer-local binding in the current buffer,
defvar
operates on the default value, which is buffer-independent, not the current (buffer-local) binding. It sets the default value if the default value is void. See Buffer-Local Variables.When you evaluate a top-level
defvar
form with C-M-x in Emacs Lisp mode (eval-defun
), a special feature ofeval-defun
arranges to set the variable unconditionally, without testing whether its value is void.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 Emacs help functions (see Documentation) look for this property.If the variable is a user option that users would want to set interactively, you should use ‘*’ as the first character of doc-string. This lets users set the variable conveniently using the
set-variable
command. Note that you should nearly always usedefcustom
instead ofdefvar
to define these variables, so that users can use M-x customize and related commands to set them. See Customization.Here are some examples. This form defines
foo
but does not initialize it:(defvar foo) => fooThis example initializes the value of
bar
to23
, and gives it a documentation string:(defvar bar 23 "The normal weight of a bar.") => barThe following form changes the documentation string for
bar
, making it a user option, but does not change the value, sincebar
already has a value. (The addition(1+ nil)
would get an error if it were evaluated, but since it is not evaluated, there is no error.)(defvar bar (1+ nil) "*The normal weight of a bar.") => bar bar => 23Here is an equivalent expression for the
defvar
special form:(defvar symbol value doc-string) == (progn (if (not (boundp 'symbol)) (setq symbol value)) (if 'doc-string (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 standard global value, established here, that should not be changed by the user or by other programs. Note that symbol is not evaluated; the symbol to be defined must appear explicitly in the
defconst
.
defconst
always evaluates value, and sets the value of symbol to the result if value is given. If symbol does have a buffer-local binding in the current buffer,defconst
sets the default value, not the buffer-local value. (But you should not be making buffer-local bindings for a symbol that is defined withdefconst
.)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—andnil
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
defcustom
1 or by the first character of theirvariable-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
specified in interactive
(see Using Interactive). However,
this feature is largely obsoleted by defcustom
(see Customization).
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 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.