Function: defvar

defvar is a special form defined in eval.c.

Signature

(defvar SYMBOL &optional INITVALUE DOCSTRING)

Documentation

Define SYMBOL as a variable, and return SYMBOL.

You are not required to define a variable in order to use it, but defining it lets you supply an initial value and documentation, which can be referred to by the Emacs help facilities and other programming tools.

If SYMBOL's value is void and the optional argument INITVALUE is provided, INITVALUE is evaluated and the result used to set SYMBOL's value. If SYMBOL is buffer-local, its default value is what is set; buffer-local values are not affected. If INITVALUE is missing, SYMBOL's value is not set.

If INITVALUE is provided, the defvar form also declares the variable as "special", so that it is always dynamically bound even if lexical-binding is t. If INITVALUE is missing, the form marks the variable "special" locally (i.e., within the current lexical scope, or the current file, if the form is at top-level), and does nothing if lexical-binding is nil.

If SYMBOL is let-bound, then this form does not affect the local let binding but the toplevel default binding instead, like
`set-toplevel-default-binding`.
(defcustom behaves similarly in this respect.)

The optional argument DOCSTRING is a documentation string for the variable.

To define a user option, use defcustom instead of defvar.

To define a buffer-local variable, use defvar-local.

View in manual

Probably introduced at or before Emacs version 1.5.

Source Code

// Defined in /usr/src/emacs/src/eval.c
{
  Lisp_Object sym, tail;

  sym = XCAR (args);
  tail = XCDR (args);

  CHECK_SYMBOL (sym);

  if (!NILP (tail))
    {
      if (!NILP (XCDR (tail)) && !NILP (XCDR (XCDR (tail))))
	error ("Too many arguments");
      Lisp_Object exp = XCAR (tail);
      tail = XCDR (tail);
      return defvar (sym, exp, CAR (tail), true);
    }
  else if (!NILP (Vinternal_interpreter_environment)
	   && (SYMBOLP (sym) && !XSYMBOL (sym)->u.s.declared_special))
    /* A simple (defvar foo) with lexical scoping does "nothing" except
       declare that var to be dynamically scoped *locally* (i.e. within
       the current file or let-block).  */
    Vinternal_interpreter_environment
      = Fcons (sym, Vinternal_interpreter_environment);
  else
    {
      /* Simple (defvar <var>) should not count as a definition at all.
	 It could get in the way of other definitions, and unloading this
	 package could try to make the variable unbound.  */
    }

  return sym;
}