— Special Form: defvar symbol [value [doc-string]]

This special form defines symbol as a value and initializes it. The definition informs a person reading your code that symbol is used as a variable that programs are likely to set or change. It is also used for all user option variables except in the preloaded parts of XEmacs. 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, defvar evaluates it and sets symbol to the result. (If value is omitted, the value of symbol is not changed in any case.)

When you evaluate a top-level defvar form with C-M-x in Emacs Lisp mode (eval-defun), a special feature of eval-defun evaluates it as a defconst. The purpose of this is to make sure the variable's value is reinitialized, when you ask for it specifically.

If symbol has a buffer-local binding in the current buffer, defvar sets the default value, not the local value. See Buffer-Local Variables.

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 SXEmacs help functions (see Documentation) look for this property.

If the first character of doc-string is ‘*’, it means that this variable is considered a user option. This lets users set the variable conveniently using the commands 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 defines symbol as a value and initializes it. It 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 standardly preloaded. 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.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 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.