Common Lisp the Language, 2nd Edition

Next: Control of Time Up: Top-Level Forms Previous: Defining Named Functions

## 5.3.2. Declaring Global Variables and Named Constants

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.

Next: Control of Time Up: Top-Level Forms Previous: Defining Named Functions