.EL File Format – Variables and scope

Names and constants

A variable name is any symbol (Lexical structure). Three kinds of symbol are constants and cannot be set or bound: nil, t, and keywords (symbols that start with :, which evaluate to themselves). An attempt to set one signals setting-constant. Evaluating a symbol that has no value signals void-variable.

Defining variables

The documentation string follows the value. It is the text shown by describe-variable. A line that starts with * was the old marker for a user option and is no longer used; use defcustom. Conventions for documentation strings are on Strings and characters.

(defvar my-counter 0
  "Number of greetings given so far.")
(defconst my-version "1.2"
  "Version string of this library.")
(defvar-local my-buffer-note nil
  "A note kept separately in each buffer.")

Lexical and dynamic binding

With dynamic binding a let changes the symbol’s value cell for as long as the body runs, so every function called from the body sees the new value. With lexical binding the binding is visible only to code written inside the let, and it is kept in the environment of any closure created there. A variable that was declared special (with defvar, defconst or defcustom) is always bound dynamically, even in a lexical file. That is why such names are written with the library prefix.

• Scope is the region of the text where a binding is visible. Extent is the period of time during which the binding exists. A lexical binding has lexical scope and indefinite extent (it lives as long as a closure refers to it). A dynamic binding has indefinite scope and dynamic extent (it ends when the let exits).
• A dynamic binding is undone by non-local exits as well, so a throw or an error restores the old value.

The lexical-binding cookie

Whether a file uses lexical binding is decided by the variable lexical-binding when the file is read. A file sets it with a first-line cookie: ;;; foo.el --- Summary -*- lexical-binding: t; -*- (File structure). History, as stated in the NEWS files:

Dynamic binding is still the default for a file without a cookie in Emacs 31. Code written for the old dialect usually works in the new one, apart from variables that were used dynamically without a defvar, closures that relied on dynamic scope, and functions such as eval that take a LEXICAL argument. The manual’s section “Converting to Lexical Binding” recommends: turn on the compiler warnings, declare every dynamically used variable with a one-argument defvar or defvar with a value, and use (eval FORM t) to evaluate a form lexically.

Binding forms

(defun make-adder (n)
  (lambda (x) (+ x n)))      ; a closure over N, with lexical-binding: t
(funcall (make-adder 3) 4)   ; => 7

(named-let loop ((i 0) (acc nil))
  (if (> i 3)
      (nreverse acc)
    (loop (1+ i) (cons i acc))))   ; => (0 1 2 3)

A closure is a function value that carries the lexical variables it refers to. With dynamic binding a lambda is only a list or a code object and carries nothing.

Buffer-local variables

A variable can have a value that belongs to one buffer. Reading it in that buffer gives the local value, otherwise the default value is used.

A let on a buffer-local variable binds the local value if there is one. A defcustom may carry :local t to make the variable automatically local (Emacs 27). Some variables are file-local or directory-local: Emacs sets them as buffer-local values when it visits a file, from the cookie, the Local Variables: list or .dir-locals.el (File structure). Connection-local variables work the same way for remote connections and processes: they are defined with connection-local-set-profile-variables and activated by criteria such as the host and user.

Aliases, obsolescence and watchers

• (defvaralias NEW OLD DOC) makes NEW another name of OLD: both share one value. indirect-variable follows the alias.
• (make-obsolete-variable OLD NEW WHEN) marks a variable obsolete; the compiler warns and describe-variable says so. The WHEN argument is mandatory since Emacs 28.
• (add-variable-watcher SYM FUNC) calls (FUNC SYMBOL NEWVAL OPERATION WHERE) whenever the variable is set, let-bound or made void. OPERATION is set, let, unlet, makunbound or defvaralias; WHERE is the buffer for a local change. remove-variable-watcher and get-variable-watchers complete the set.

Generalized variables

A place is anything that holds a value: a variable, (car X), (nth N L), (aref V I), (gethash K H), (alist-get K A), (plist-get P K), (buffer-local-value S B) and others. setf stores into a place; push, pop, cl-incf, add-to-list (for variables only), cl-pushnew, setf and incf take places as well. New places are defined with gv-define-setter, gv-define-simple-setter or (declare (gv-setter …)) on a function. In Emacs 29 many seldom-used places were made obsolete, and make-obsolete-generalized-variable was added.

(let ((l (list 1 2 3)))
  (setf (nth 1 l) 'two)
  l)                           ; => (1 two 3)

Customize: defcustom, defgroup, defface

defcustom has the syntax (defcustom SYMBOL STANDARD DOC [KEYWORD VALUE]…). STANDARD is evaluated when the variable is first needed. defgroup declares a group with (defgroup SYMBOL MEMBERS DOC :group PARENT …).

Type specifications

(defgroup my-greet nil "Greeting options." :group 'convenience)

(defcustom my-greet-style 'formal
  "How `my-greet' words its message."
  :type '(choice (const :tag "Formal" formal)
                 (const :tag "Casual" casual))
  :group 'my-greet
  :package-version '(my-greet . "1.0")
  :safe #'symbolp)

Faces

(defface NAME SPEC DOC [KEYWORD VALUE]…) defines a face. SPEC is a list of (DISPLAY ATTRIBUTES) clauses; DISPLAY is t or a list of conditions such as ((class color) (background dark)), and ATTRIBUTES is a plist such as (:foreground "red" :weight bold :inherit shadow). The first clause whose condition matches the frame is used. Keywords :group, :version and :package-version are as for options. From Emacs 31 a face that inherits from itself, directly or indirectly, signals an error.

Not described

Known, not yet covered

• Reference: the full list of face attributes and the display conditions of a face specification.
• Reference: the less common defcustom type keywords (:tag, :match, :validate, :inline) and the custom themes (deftheme, custom-theme-set-variables).
• Reference: the exact criteria and profile functions of connection-local variables, and the rules for deciding when a file-local value is safe (File structure).
• Reference: the places defined by cl-lib and the full gv macro interface.

See also

• File structure – the cookie, file-local and directory-local variables
• Evaluation – how a symbol is evaluated and how forms are run
• Functions – lambda, closures and argument lists
• Byte-compilation – the warnings for free variables and a missing cookie
• Variables – the manual’s chapter on variables
• Customization Settings – the manual’s chapter on defcustom, groups and faces