(lispref.info)Defining Variables


Next: Accessing Variables Prev: Void Variables Up: Variables

Defining Global Variables
=========================

   You may announce your intention to use a symbol as a global variable
with a definition, using `defconst' or `defvar'.

   In Emacs Lisp, definitions serve three purposes.  First, they inform
the user who reads the code that certain symbols are *intended* to be
used 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 programs will
change the variable.  Emacs Lisp does not restrict the ways in which a
variable can be used based on `defconst' or `defvar' declarations.
However, it also makes a difference for initialization: `defconst'
unconditionally initializes the variable, while `defvar' initializes it
only if it is void.

   One would expect user option variables to be defined with
`defconst', since programs do not change them.  Unfortunately, this has
bad results if the definition is in a library that is not preloaded:
`defconst' would override any prior value when the library is loaded.
Users would like to be able to set the option in their init files, and
override the default value given in the definition.  For this reason,
user options must be defined with `defvar'.

 - Special Form: defvar SYMBOL [VALUE [DOC-STRING]]
     This special form informs a person reading your code that SYMBOL
     will be used as a variable that the programs are likely to set or
     change.  It is also used for all user option variables except in
     the preloaded parts of Emacs.  Note that SYMBOL is not evaluated;
     the symbol to be defined must appear explicitly in the `defvar'.

     If SYMBOL already has a value (i.e., it is not void), VALUE is not
     even evaluated, and SYMBOL's value remains unchanged.  If SYMBOL
     is void and VALUE is specified, it is evaluated and SYMBOL is set
     to the result.  (If VALUE is not specified, the value of SYMBOL is
     not changed in any case.)

     If SYMBOL has a buffer-local binding in the current buffer,
     `defvar' sets the default value, not the local value.

     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 first character of DOC-STRING is `*', it means that this
     variable is considered to be a user option.  This affects commands
     such as `set-variable' and `edit-options'.

     For example, this form defines `foo' but does not set its value:

          (defvar foo)
               => foo

     The following example sets 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+ 23)' is not even
     performed.)

          (defvar bar (1+ 23)
            "*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))
            (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 informs a person reading your code that SYMBOL
     has a global value, established here, that will not normally be
     changed or locally bound by the execution of the program.  The
     user, however, may be welcome to change it.  Note that SYMBOL is
     not evaluated; the symbol to be defined must appear explicitly in
     the `defconst'.

     `defconst' always evaluates VALUE and sets the global value of
     SYMBOL to the result, provided VALUE is given.  If SYMBOL has a
     buffer-local binding in the current buffer, `defconst' sets the
     default value, not the local value.

     *Please note:* don't use `defconst' for user option variables in
     libraries that are not normally loaded.  The user should be able
     to specify a value for such a variable in the `.emacs' file, so
     that it will be in effect if and when the library is loaded later.

     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 "Pi to one place.")
               => pi
          (setq pi 4)
               => pi
          pi
               => 4

 - Function: user-variable-p VARIABLE
     This function returns `t' if VARIABLE is a user option, intended
     to be set by the user for customization, `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 by the
     first character of the `variable-documentation' property.  If the
     property exists and is a string, and its first character is `*',
     then the variable is a user option.

   Note that if the `defconst' and `defvar' special forms are used
while the variable has a local binding, the local binding's value is
set, and the global binding is not changed.  This would be confusing.
But the normal way to use these special forms is at top level in a file,
where no local binding should be in effect.


automatically generated by info2www