Global variables have values that last until explicitly superseded with new values. Sometimes it is useful to give a variable a local value—a value that takes effect only within a certain part of a Lisp program. When a variable has a local value, we say that it is locally bound to that value, and that it is a local variable.
For example, when a function is called, its argument variables
receive local values, which are the actual arguments supplied to the
function call; these local bindings take effect within the body of the
function. To take another example, the let special form
explicitly establishes local bindings for specific variables, which
take effect only within the body of the let form.
We also speak of the global binding, which is where (conceptually) the global value is kept.
Establishing a local binding saves away the variable’s previous
value (or lack of one). We say that the previous value is
shadowed. Both global and local values may be shadowed. If a
local binding is in effect, using setq on the local variable
stores the specified value in the local binding. When that local
binding is no longer in effect, the previously shadowed value (or lack
of one) comes back.
A variable can have more than one local binding at a time (e.g., if
there are nested let forms that bind the variable). The
current binding is the local binding that is actually in effect.
It determines the value returned by evaluating the variable symbol,
and it is the binding acted on by setq.
For most purposes, you can think of the current binding as the innermost local binding, or the global binding if there is no local binding. To be more precise, a rule called the scoping rule determines where in a program a local binding takes effect. The default scoping rule in Emacs Lisp is called dynamic scoping, which simply states that the current binding at any given point in the execution of a program is the most recently-created binding for that variable that still exists. For details about dynamic scoping, and an alternative scoping rule called lexical scoping, see Scoping Rules for Variable Bindings. Lately Emacs is moving towards using lexical binding in more and more places, with the goal of eventually making lexical binding the default. In particular, all Emacs Lisp source files and the *scratch* buffer use lexical scoping.
The special forms let and let* exist to create local
bindings:
This special form sets up local bindings for a certain set of
variables, as specified by bindings, and then evaluates all of
the forms in textual order. Its return value is the value of
the last form in forms. The local bindings set up by let
will be in effect only within the body of forms.
Each of the bindings is either (i) a symbol, in which case
that symbol is locally bound to nil; or (ii) a list of the
form (symbol value-form), in which case
symbol is locally bound to the result of evaluating
value-form. If value-form is omitted, nil is used.
All of the value-forms in bindings are evaluated in the
order they appear and before binding any of the symbols to them.
Here is an example of this: z is bound to the old value of
y, which is 2, not the new value of y, which is 1.
(setq y 2)
⇒ 2
(let ((y 1)
(z y))
(list y z))
⇒ (1 2)
On the other hand, the order of bindings is unspecified: in the following example, either 1 or 2 might be printed.
(let ((x 1)
(x 2))
(print x))
Therefore, avoid binding a variable more than once in a single
let form.
This special form is like let, but it binds each variable right
after computing its local value, before computing the local value for
the next variable. Therefore, an expression in bindings can
refer to the preceding symbols bound in this let* form.
Compare the following example with the example above for let.
(setq y 2)
⇒ 2
(let* ((y 1)
(z y)) ; Use the just-established value of y.
(list y z))
⇒ (1 1)
Basically, the let* binding of x and y in the
previous example is equivalent to using nested let bindings:
(let ((y 1))
(let ((z y))
(list y z)))
This special form is like let*, but all the variables are bound
before any of the local values are computed. The values are then
assigned to the locally bound variables. This is only useful when
lexical binding is in effect, and you want to create closures that
refer to bindings that would otherwise not yet be in effect when using
let*.
For instance, here’s a closure that removes itself from a hook after being run once:
(letrec ((hookfun (lambda ()
(message "Run once")
(remove-hook 'post-command-hook hookfun))))
(add-hook 'post-command-hook hookfun))
This special form is like let, but it binds all variables
dynamically. This is rarely useful—you usually want to bind normal
variables lexically, and special variables (i.e., variables that are
defined with defvar) dynamically, and this is what let
does.
dlet can be useful when interfacing with old code that assumes
that certain variables are dynamically bound (see Dynamic Binding), but it’s impractical to defvar these variables.
dlet will temporarily make the bound variables special, execute
the forms, and then make the variables non-special again.
This special form is a looping construct inspired from the
Scheme language. It is similar to let: It binds the variables in
bindings, and then evaluates body. However,
named-let also binds name to a
local function whose formal arguments are the variables in bindings
and whose body is body. This allows body to call itself
recursively by calling
name, where the arguments passed to name are used as the
new values of the bound variables in the recursive invocation.
Example of a loop summing a list of numbers:
(named-let sum ((numbers '(1 2 3 4))
(running-sum 0))
(if numbers
(sum (cdr numbers) (+ running-sum (car numbers)))
running-sum))
⇒ 10
Recursive calls to name that occur in tail positions in body are guaranteed to be optimized as tail calls, which means that they will not consume any additional stack space no matter how deeply the recursion runs. Such recursive calls will effectively jump to the top of the loop with new values for the variables.
A function call is in the tail position if it’s the very last thing
done so that the value returned by the call is the value of body
itself, as is the case in the recursive call to sum above.
Warning: named-let works as expected only when
lexical-binding is enabled. See Lexical Binding.
Here is a complete list of the other facilities that create local bindings:
Variables can also have buffer-local bindings (see Buffer-Local Variables); a few variables have terminal-local bindings (see Multiple Terminals). These kinds of bindings work somewhat like ordinary local bindings, but they are localized depending on where you are in Emacs.