A variable definition is a construct that announces your
intention to use a symbol as a global variable. It uses the special
forms defvar or defconst, which are documented below.
A variable definition serves three purposes. First, it informs
people who read the code that the symbol is 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
etags, allowing them to find where the variable was defined.
The difference between defconst and 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 defconst. One
notable difference between the two forms is that defconst
unconditionally initializes the variable, whereas defvar
initializes it only if it is originally void.
To define a customizable variable, you should use defcustom
(which calls defvar as a subroutine). See Defining Customization Variables.
This special form defines symbol as a variable. Note that
symbol is not evaluated; the symbol to be defined should appear
explicitly in the defvar form. The variable is marked as
special, meaning that it should always be dynamically bound
(see Scoping Rules for Variable Bindings).
If value is specified, and symbol is void (i.e., it has no dynamically bound value; see When a Variable is Void), then value is evaluated and symbol is set to the result. But if symbol is not void, value is not evaluated, and symbol’s value is left unchanged. If value is omitted, the value of symbol is not changed in any case.
Note that specifying a value, even nil, marks the variable as
special permanently. Whereas if value is omitted then the
variable is only marked special locally (i.e. within the current
lexical scope, or file if at the top-level). This can be useful for
suppressing byte compilation warnings, see Compiler Errors.
If symbol has a buffer-local binding in the current buffer,
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. See Buffer-Local Variables.
If symbol is already let bound (e.g., if the defvar
form occurs in a let form), then defvar sets the toplevel
default value, like set-default-toplevel-value.
The let binding remains in effect until its binding construct exits.
See Scoping Rules for Variable Bindings.
When you evaluate a top-level defvar form with C-M-x
(eval-defun) or with C-x C-e (eval-last-sexp) in
Emacs Lisp mode, a special feature of these two commands arranges to
set the variable unconditionally, without testing whether its value is
void.
If the doc-string argument is supplied, it specifies the
documentation string for the variable (stored in the symbol’s
variable-documentation property). See Documentation.
Here are some examples. This form defines foo but does not
initialize it:
(defvar foo)
⇒ foo
This example initializes the value of bar to 23, and gives
it a documentation string:
(defvar bar 23
"The normal weight of a bar.")
⇒ bar
The defvar form returns symbol, but it is normally used
at top level in a file where its value does not matter.
For a more elaborate example of using defvar without a value,
see Local defvar example.
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.
The defconst form, like defvar, marks the variable as
special, meaning that it should always be dynamically bound
(see Scoping Rules for Variable Bindings). In addition, it marks the variable as
risky (see File Local Variables).
defconst always evaluates value, and sets the value of
symbol to the result. 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 with
defconst.)
An example of the use of defconst is Emacs’s definition of
float-pi—the mathematical constant pi, which ought not
to be changed by anyone (attempts by the Indiana State Legislature
notwithstanding). As the second form illustrates, however,
defconst is only advisory.
(defconst float-pi 3.141592653589793 "The value of Pi.")
⇒ float-pi
(setq float-pi 3)
⇒ float-pi
float-pi
⇒ 3
Warning: If you use a defconst or defvar
special form while the variable has a local binding (made with
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.