GNU Info

(elisp)Defining Variables

---

Next: Tips for Defining Prev: Void Variables Up: Variables

---

Enter node , (file) or (file)node

Defining Global 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.

 - Special Form: defvar symbol [value [doc-string]]
     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.  Note:
     Buffer-Local Variables.

     When you evaluate a top-level `defvar' form with `C-M-x' in Emacs
     Lisp mode (`eval-defun'), a special feature of `eval-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 (Note: 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
     use `defcustom' instead of `defvar' to define these variables, so
     that users can use `M-x customize' and related commands to set
     them.  Note: Customization.

     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 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+ 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
               => 23

     Here 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.

 - Special Form: defconst symbol [value [doc-string]]
     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 with
     `defconst'.)

     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

 - Function: user-variable-p variable
     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 either
     though being declared using `defcustom'(1) or by the first
     character of their `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 specified
in `interactive' (Note: Using Interactive).  However, this feature is
largely obsoleted by `defcustom' (Note: 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.

   ---------- Footnotes ----------

   (1) They may also be declared equivalently in `cus-start.el'.