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. The defvar form also declares the variable as "special", so that it is always dynamically bound even if lexical-binding is t.

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 SYMBOL has a local binding, then this form affects the local binding. This is usually not what you want. Thus, if you need to load a file defining variables, with this form or with defconst or defcustom, you should always load that file _outside_ any bindings for these variables. (defconst and defcustom behave 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.

Probably introduced at or before Emacs version 1.5.

Source Code

// Defined in /usr/src/emacs/src/eval.c
{
  Lisp_Object sym, tem, 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);

      tem = Fdefault_boundp (sym);
      tail = XCDR (tail);

      /* Do it before evaluating the initial value, for self-references.  */
      Finternal__define_uninitialized_variable (sym, CAR (tail));

      if (NILP (tem))
	Fset_default (sym, eval_sub (exp));
      else
	{ /* Check if there is really a global binding rather than just a let
	     binding that shadows the global unboundness of the var.  */
	  union specbinding *binding = default_toplevel_binding (sym);
	  if (binding && EQ (specpdl_old_value (binding), Qunbound))
	    {
	      set_specpdl_old_value (binding, eval_sub (exp));
	    }
	}
    }
  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;
}