Info Catalog elisp: Void Variables elisp: Variables elisp: Tips for Defining

elisp: Defining Variables

 
 11.5 Defining Global Variables
 ==============================
 
 A “variable definition” is a construct that announces your intention to
 use a symbol as a global variable.  It uses the special forms ‘defvar’
 or ‘defconst’, which are documented below.
 
    A variable definition serves three purposes.  First, it informs
 people who read the code that the symbol is _intended_ to be used a
 certain way (as a variable).  Second, it informs the Lisp system of
 this, optionally supplying an initial value and a documentation string.
 Third, it provides information to programming tools such as ‘etags’,
 allowing them to find where the variable was defined.
 
    The difference between ‘defconst’ and ‘defvar’ is mainly a matter of
 intent, serving to inform human readers of whether the value should ever
 change.  Emacs Lisp does not actually prevent you from changing the
 value of a variable defined with ‘defconst’.  One notable difference
 between the two forms is that ‘defconst’ unconditionally initializes the
 variable, whereas ‘defvar’ initializes it only if it is originally void.
 
    To define a customizable variable, you should use ‘defcustom’ (which
 calls ‘defvar’ as a subroutine).  Variable Definitions.
 
  -- Special Form: defvar symbol [value [doc-string]]
      This special form defines SYMBOL as a variable.  Note that SYMBOL
      is not evaluated; the symbol to be defined should appear explicitly
      in the ‘defvar’ form.  The variable is marked as “special”, meaning
      that it should always be dynamically bound (Variable
      Scoping).
 
      If VALUE is specified, and SYMBOL is void (i.e., it has no
      dynamically bound value; Void Variables), then VALUE is
      evaluated and SYMBOL is set to the result.  But if SYMBOL is not
      void, VALUE is not evaluated, and SYMBOL’s value is left 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’ acts on the default value, which is buffer-independent,
      rather than the buffer-local binding.  It sets the default value if
      the default value is void.  Buffer-Local Variables.
 
      If SYMBOL is already lexically bound (e.g., if the ‘defvar’ form
      occurs in a ‘let’ form with lexical binding enabled), then ‘defvar’
      sets the dynamic value.  The lexical binding remains in effect
      until its binding construct exits.  Variable Scoping.
 
      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 is supplied, it specifies the
      documentation string for the variable (stored in the symbol’s
      ‘variable-documentation’ property).  Documentation.
 
      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 ‘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’.
 
      The ‘defconst’ form, like ‘defvar’, marks the variable as
      “special”, meaning that it should always be dynamically bound
      (Variable Scoping).  In addition, it marks the variable as
      risky (File Local Variables).
 
      ‘defconst’ always evaluates VALUE, and sets the value of SYMBOL to
      the result.  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’.)
 
      An example of the use of ‘defconst’ is Emacs’s definition of
      ‘float-pi’—the mathematical constant pi, which ought not to be
      changed by anyone (attempts by the Indiana State Legislature
      notwithstanding).  As the second form illustrates, however,
      ‘defconst’ is only advisory.
 
           (defconst float-pi 3.141592653589793 "The value of Pi.")
                ⇒ float-pi
           (setq float-pi 3)
                ⇒ float-pi
           float-pi
                ⇒ 3
 
    *Warning:* If you use a ‘defconst’ or ‘defvar’ special form while the
 variable has a local binding (made with ‘let’, or a function argument),
 it sets the local binding rather than the global binding.  This is not
 what you usually want.  To prevent this, 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.
 

Info Catalog elisp: Void Variables elisp: Variables elisp: Tips for Defining