When loading an Emacs Lisp file or evaluating a Lisp buffer, lexical
binding is enabled if the buffer-local variable
If this buffer-local variable is non-
nil, Emacs Lisp files and buffers are evaluated using lexical binding instead of dynamic binding. (However, special variables are still dynamically bound; see below.) If
nil, dynamic binding is used for all local variables. This variable is typically set for a whole Emacs Lisp file, as a file local variable (see File Local Variables). Note that unlike other such variables, this one must be set in the first line of a file.
When evaluating Emacs Lisp code directly using an
lexical binding is enabled if the lexical argument to
eval is non-
nil. See Eval.
Even when lexical binding is enabled, certain variables will
continue to be dynamically bound. These are called special
variables. Every variable that has been defined with
defconst is a special variable
(see Defining Variables). All other variables are subject to
defvar without a value, it is possible to bind a variable
dynamically just in one file, or in just one part of a file while
still binding it lexically elsewhere. For example:
(let (_) (defvar x) ; Let-bindings of
xwill be dynamic within this let. (let ((x -99)) ; This is a dynamic binding of
x. (defun get-dynamic-x () x))) (let ((x 'lexical)) ; This is a lexical binding of
x. (defun get-lexical-x () x)) (let (_) (defvar x) (let ((x 'dynamic)) (list (get-lexical-x) (get-dynamic-x)))) ⇒ (lexical dynamic)
This function returns non-
nilif symbol is a special variable (i.e., it has a
defconstvariable definition). Otherwise, the return value is
The use of a special variable as a formal argument in a function is discouraged. Doing so gives rise to unspecified behavior when lexical binding mode is enabled (it may use lexical binding sometimes, and dynamic binding other times).
Converting an Emacs Lisp program to lexical binding is easy. First,
add a file-local variable setting of
t in the header line of the Emacs Lisp source file (see File Local Variables). Second, check that every variable in the program
which needs to be dynamically bound has a variable definition, so that
it is not inadvertently bound lexically.
A simple way to find out which variables need a variable definition
is to byte-compile the source file. See Byte Compilation. If a
non-special variable is used outside of a
let form, the
byte-compiler will warn about reference or assignment to a free
variable. If a non-special variable is bound but not used within a
let form, the byte-compiler will warn about an unused lexical
variable. The byte-compiler will also issue a warning if you use a
special variable as a function argument.
(To silence byte-compiler warnings about unused variables, just use a variable name that starts with an underscore. The byte-compiler interprets this as an indication that this is a variable known not to be used.)