Common Lisp the Language, 2nd Edition
The defvar and defparameter special forms are the usual means of specifying globally defined variables. The defconstant special form is used for defining named constants.
[Macro]
defvar name [initial-value [documentation]]
defparameter name initial-value [documentation]
defconstant name initial-value [documentation]
defvar is the recommended way to declare the use of a special variable in a program.
(defvar variable)
proclaims variable to be special (see proclaim), and may perform other system-dependent bookkeeping actions.
X3J13 voted in June 1987 (DEFVAR-INITIALIZATION) to clarify
that if no initial-value form is provided, defvar
does not change the value of the variable;
if no initial-value form is provided and the variable
has no value, defvar does not give it a value.
If a second argument form is supplied,
(defvar variable initial-value)
then variable is initialized to the result of evaluating the form initial-value unless it already has a value. The initial-value form is not evaluated unless it is used; this fact is useful if evaluation of the initial-value form does something expensive like creating a large data structure.
X3J13 voted in June 1987 (DEFVAR-INIT-TIME) to clarify that
evaluation of the initial-value and the initialization of the
variable occur, if at all, at the time the defvar form is executed,
and that the initial-value form is evaluated
if and only if the variable does not already have a value.
The initialization is performed by assignment and thus assigns a global value to the variable unless there are currently special bindings of that variable. Normally there should not be any such special bindings.
defvar also provides a good place to put a comment describing the meaning of the variable, whereas an ordinary special proclamation offers the temptation to declare several variables at once and not have room to describe them all.
(defvar *visible-windows* 0 "Number of windows at least partially visible on the screen")
defparameter is similar to defvar, but defparameter requires an initial-value form, always evaluates the form, and assigns the result to the variable. The semantic distinction is that defvar is intended to declare a variable changed by the program, whereas defparameter is intended to declare a variable that is normally constant but can be changed (possibly at run time), where such a change is considered a change to the program. defparameter therefore does not indicate that the quantity never changes; in particular, it does not license the compiler to build assumptions about the value into programs being compiled.
defconstant is like defparameter but does assert that the value of the variable name is fixed and does license the compiler to build assumptions about the value into programs being compiled. (However, if the compiler chooses to replace references to the name of the constant by the value of the constant in code to be compiled, perhaps in order to allow further optimization, the compiler must take care that such ``copies'' appear to be eql to the object that is the actual value of the constant. For example, the compiler may freely make copies of numbers but must exercise care when the value is a list.)
It is an error if there are any special bindings of the variable at the time the defconstant form is executed (but implementations may or may not check for this).
Once a name has been declared by defconstant to be constant, any further assignment to or binding of that special variable is an error. This is the case for such system-supplied constants as t and most-positive-fixnum. A compiler may also choose to issue warnings about bindings of the lexical variable of the same name.
X3J13 voted in January 1989
(DEFCONSTANT-SPECIAL)
to clarify the preceding paragraph by specifying
that it is an error to rebind constant symbols
as either lexical or special variables.
Consequently, a valid reference to a symbol declared with defconstant
always refers to its global value.
(Unfortunately, this violates the principle of referential transparency,
for one cannot always choose names for lexical variables without regard
to surrounding context.)
For any of these constructs, the documentation should be a string. The string is attached to the name of the variable, parameter, or constant under the variable documentation type; see the documentation function.
X3J13 voted in March 1988
(DEFVAR-DOCUMENTATION)
to clarify that the documentation-string
is not evaluated but must appear as a literal string when the defvar,
defparameter, or defconstant form is evaluated.
For example, the form
(defvar *avoid-registers* nil "Compilation control switch #43")
is legitimate, but
(defvar *avoid-registers* nil
(format nil "Compilation control switch #~D"
(incf *compiler-switch-number*)))
is erroneous because the call to format is not a literal string.
(On the other hand, the form
(defvar *avoid-registers* nil
#.(format nil "Compilation control switch #~D"
(incf *compiler-switch-number*)))
might be used to accomplish the same purpose, because the call to
format is evaluated at read time; when the defvar form
is evaluated, only the result of the call to format, a string,
appears in the defvar form.)
These constructs are normally used only as top-level forms. The value returned by each of these constructs is the name declared.