The evaluation of expressions in Emacs Lisp is performed by the
Lisp interpreter—a program that receives a Lisp object as input
and computes its value as an expression. How it does this depends
on the data type of the object, according to rules described in this
chapter. The interpreter runs automatically to evaluate portions of
your program, but can also be called explicitly via the Lisp primitive
function eval.
The Lisp interpreter, or evaluator, is the part of Emacs that computes the value of an expression that is given to it. When a function written in Lisp is called, the evaluator computes the value of the function by evaluating the expressions in the function body. Thus, running any Lisp program really means running the Lisp interpreter.
A Lisp object that is intended for evaluation is called a form or expression8. The fact that forms are data objects and not merely text is one of the fundamental differences between Lisp-like languages and typical programming languages. Any object can be evaluated, but in practice only numbers, symbols, lists and strings are evaluated very often.
In subsequent sections, we will describe the details of what evaluation means for each kind of form.
It is very common to read a Lisp form and then evaluate the form,
but reading and evaluation are separate activities, and either can be
performed alone. Reading per se does not evaluate anything; it
converts the printed representation of a Lisp object to the object
itself. It is up to the caller of read to specify whether this
object is a form to be evaluated, or serves some entirely different
purpose. See Input Functions.
Evaluation is a recursive process, and evaluating a form often
involves evaluating parts within that form. For instance, when you
evaluate a function call form such as (car x), Emacs
first evaluates the argument (the subform x). After evaluating
the argument, Emacs executes the function (car), and if
the function is written in Lisp, execution works by evaluating the
body of the function (in this example, however, car is
not a Lisp function; it is a primitive function implemented in C).
See Functions, for more information about functions and function
calls.
Evaluation takes place in a context called the environment, which consists of the current values and bindings of all Lisp variables (see Variables).9 Whenever a form refers to a variable without creating a new binding for it, the variable evaluates to the value given by the current environment. Evaluating a form may also temporarily alter the environment by binding variables (see Local Variables).
Evaluating a form may also make changes that persist; these changes
are called side effects. An example of a form that produces a
side effect is (setq foo 1).
Do not confuse evaluation with command key interpretation. The
editor command loop translates keyboard input into a command (an
interactively callable function) using the active keymaps, and then
uses call-interactively to execute that command. Executing the
command usually involves evaluation, if the command is written in
Lisp; however, this step is not considered a part of command key
interpretation. See Command Loop.
A Lisp object that is intended to be evaluated is called a form (or an expression). How Emacs evaluates a form depends on its data type. Emacs has three different kinds of form that are evaluated differently: symbols, lists, and all other types. This section describes all three kinds, one by one, starting with the other types, which are self-evaluating forms.
A self-evaluating form is any form that is not a list or
symbol. Self-evaluating forms evaluate to themselves: the result of
evaluation is the same object that was evaluated. Thus, the number 25
evaluates to 25, and the string "foo" evaluates to the string
"foo". Likewise, evaluating a vector does not cause evaluation
of the elements of the vector—it returns the same vector with its
contents unchanged.
'123 ; A number, shown without evaluation.
⇒ 123
123 ; Evaluated as usual—result is the same.
⇒ 123
(eval '123) ; Evaluated "by hand"—result is the same.
⇒ 123
(eval (eval '123)) ; Evaluating twice changes nothing.
⇒ 123
A self-evaluating form yields a value that becomes part of the program,
and you should not try to modify it via setcar, aset or
similar operations. The Lisp interpreter might unify the constants
yielded by your program’s self-evaluating forms, so that these
constants might share structure. See Mutability.
It is common to write numbers, characters, strings, and even vectors in Lisp code, taking advantage of the fact that they self-evaluate. However, it is quite unusual to do this for types that lack a read syntax, because there’s no way to write them textually. It is possible to construct Lisp expressions containing these types by means of a Lisp program. Here is an example:
;; Build an expression containing a buffer object.
(setq print-exp (list 'print (current-buffer)))
⇒ (print #<buffer eval.texi>)
;; Evaluate it.
(eval print-exp)
⊣ #<buffer eval.texi>
⇒ #<buffer eval.texi>
When a symbol is evaluated, it is treated as a variable. The result is the variable’s value, if it has one. If the symbol has no value as a variable, the Lisp interpreter signals an error. For more information on the use of variables, see Variables.
In the following example, we set the value of a symbol with
setq. Then we evaluate the symbol, and get back the value that
setq stored.
(setq a 123)
⇒ 123
(eval 'a)
⇒ 123
a
⇒ 123
The symbols nil and t are treated specially, so that the
value of nil is always nil, and the value of t is
always t; you cannot set or bind them to any other values. Thus,
these two symbols act like self-evaluating forms, even though
eval treats them like any other symbol. A symbol whose name
starts with ‘:’ also self-evaluates in the same way; likewise,
its value ordinarily cannot be changed. See Variables that Never Change.
A form that is a nonempty list is either a function call, a macro call, or a special form, according to its first element. These three kinds of forms are evaluated in different ways, described below. The remaining list elements constitute the arguments for the function, macro, or special form.
The first step in evaluating a nonempty list is to examine its first element. This element alone determines what kind of form the list is and how the rest of the list is to be processed. The first element is not evaluated, as it would be in some Lisp dialects such as Scheme.
If the first element of the list is a symbol then evaluation examines the symbol’s function cell, and uses its contents instead of the original symbol. If the contents are another symbol, this process, called symbol function indirection, is repeated until it obtains a non-symbol. See Naming a Function, for more information about symbol function indirection. We eventually obtain a non-symbol, which ought to be a function or other suitable object.
More precisely, we should now have a Lisp function (a lambda
expression), a byte-code function, a primitive function, a Lisp macro,
a special form, or an autoload object. Each of these types is a case
described in one of the following sections. If the object is not one
of these types, Emacs signals an invalid-function error.
The following example illustrates the symbol indirection process.
We use fset to set the function cell of a symbol and
symbol-function to get the function cell contents
(see Accessing Function Cell Contents). Specifically, we store the symbol
car into the function cell of first, and the symbol
first into the function cell of erste.
;; Build this function cell linkage:
;; ------------- ----- ------- -------
;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
;; ------------- ----- ------- -------
(symbol-function 'car)
⇒ #<subr car>
(fset 'first 'car)
⇒ car
(fset 'erste 'first)
⇒ first
(erste '(1 2 3)) ; Call the function referenced by erste.
⇒ 1
By contrast, the following example calls a function without any symbol function indirection, because the first element is an anonymous Lisp function, not a symbol.
((lambda (arg) (erste arg))
'(1 2 3))
⇒ 1
Executing the function itself evaluates its body; this does involve
symbol function indirection when calling erste.
This form is rarely used and is now deprecated. Instead, you should write it as:
(funcall (lambda (arg) (erste arg))
'(1 2 3))
or just
(let ((arg '(1 2 3))) (erste arg))
The built-in function indirect-function provides an easy way to
perform symbol function indirection explicitly.
This function returns the meaning of function as a function. If function is a symbol, then it finds function’s function definition and starts over with that value. If function is not a symbol, then it returns function itself.
This function returns nil if the final symbol is unbound.
There is also a second, optional argument that is obsolete and has no effect.
Here is how you could define indirect-function in Lisp:
(defun indirect-function (function)
(if (and function
(symbolp function))
(indirect-function (symbol-function function))
function))
If the first element of a list being evaluated is a Lisp function
object, byte-code object or primitive function object, then that list is
a function call. For example, here is a call to the function
+:
(+ 1 x)
The first step in evaluating a function call is to evaluate the
remaining elements of the list from left to right. The results are the
actual argument values, one value for each list element. The next step
is to call the function with this list of arguments, effectively using
the function apply (see Calling Functions). If the function
is written in Lisp, the arguments are used to bind the argument
variables of the function (see Lambda Expressions); then the forms
in the function body are evaluated in order, and the value of the last
body form becomes the value of the function call.
If the first element of a list being evaluated is a macro object, then the list is a macro call. When a macro call is evaluated, the elements of the rest of the list are not initially evaluated. Instead, these elements themselves are used as the arguments of the macro. The macro definition computes a replacement form, called the expansion of the macro, to be evaluated in place of the original form. The expansion may be any sort of form: a self-evaluating constant, a symbol, or a list. If the expansion is itself a macro call, this process of expansion repeats until some other sort of form results.
Ordinary evaluation of a macro call finishes by evaluating the expansion. However, the macro expansion is not necessarily evaluated right away, or at all, because other programs also expand macro calls, and they may or may not evaluate the expansions.
Normally, the argument expressions are not evaluated as part of computing the macro expansion, but instead appear as part of the expansion, so they are computed when the expansion is evaluated.
For example, given a macro defined as follows:
(defmacro cadr (x) (list 'car (list 'cdr x)))
an expression such as (cadr (assq 'handler list)) is a macro
call, and its expansion is:
(car (cdr (assq 'handler list)))
Note that the argument (assq 'handler list) appears in the
expansion.
See Macros, for a complete description of Emacs Lisp macros.
A special form is a primitive specially marked so that its arguments are not all evaluated. Most special forms define control structures or perform variable bindings—things which functions cannot do.
Each special form has its own rules for which arguments are evaluated and which are used without evaluation. Whether a particular argument is evaluated may depend on the results of evaluating other arguments.
If an expression’s first symbol is that of a special form, the
expression should follow the rules of that special form; otherwise,
Emacs’s behavior is not well-defined (though it will not crash). For
example, ((lambda (x) x . 3) 4) contains a subexpression that
begins with lambda but is not a well-formed lambda
expression, so Emacs may signal an error, or may return 3 or 4 or
nil, or may behave in other ways.
This predicate tests whether its argument is a special form, and
returns t if so, nil otherwise.
Here is a list, in alphabetical order, of all of the special forms in Emacs Lisp with a reference to where each is described.
andcatchcondsee Conditionals
condition-casedefconstdefvarfunctionifsee Conditionals
interactivesee Interactive Call
lambdaletlet*see Local Variables
orprog1prog2prognsee Sequencing
quotesee Quoting
save-current-buffersave-excursionsee Excursions
save-restrictionsee Narrowing
setqsetq-defaultunwind-protectsee Nonlocal Exits
whilesee Iteration
Common Lisp note: Here are some comparisons of special forms in GNU Emacs Lisp and Common Lisp.
setq,if, andcatchare special forms in both Emacs Lisp and Common Lisp.save-excursionis a special form in Emacs Lisp, but doesn’t exist in Common Lisp.throwis a special form in Common Lisp (because it must be able to throw multiple values), but it is a function in Emacs Lisp (which doesn’t have multiple values).
The autoload feature allows you to call a function or macro whose function definition has not yet been loaded into Emacs. It specifies which file contains the definition. When an autoload object appears as a symbol’s function definition, calling that symbol as a function automatically loads the specified file; then it calls the real definition loaded from that file. The way to arrange for an autoload object to appear as a symbol’s function definition is described in Autoload.
The special form quote returns its single argument, as written,
without evaluating it. This provides a way to include constant symbols
and lists, which are not self-evaluating objects, in a program. (It is
not necessary to quote self-evaluating objects such as numbers, strings,
and vectors.)
This special form returns object, without evaluating it. The returned value might be shared and should not be modified. See Self-Evaluating Forms.
Because quote is used so often in programs, Lisp provides a
convenient read syntax for it. An apostrophe character (‘'’)
followed by a Lisp object (in read syntax) expands to a list whose first
element is quote, and whose second element is the object. Thus,
the read syntax 'x is an abbreviation for (quote x).
Here are some examples of expressions that use quote:
(quote (+ 1 2))
⇒ (+ 1 2)
(quote foo)
⇒ foo
'foo
⇒ foo
''foo
⇒ 'foo
'(quote foo)
⇒ 'foo
['foo]
⇒ ['foo]
Although the expressions (list '+ 1 2) and '(+ 1 2)
both yield lists equal to (+ 1 2), the former yields a
freshly-minted mutable list whereas the latter yields a list
built from conses that might be shared and should not be modified.
See Self-Evaluating Forms.
Other quoting constructs include function (see Anonymous Functions), which causes an anonymous lambda expression written in Lisp
to be compiled, and ‘`’ (see Backquote), which is used to quote
only part of a list, while computing and substituting other parts.
Backquote constructs allow you to quote a list, but
selectively evaluate elements of that list. In the simplest case, it
is identical to the special form
quote
(described in the previous section; see Quoting).
For example, these two forms yield identical results:
`(a list of (+ 2 3) elements)
⇒ (a list of (+ 2 3) elements)
'(a list of (+ 2 3) elements)
⇒ (a list of (+ 2 3) elements)
The special marker ‘,’ inside of the argument to backquote indicates a value that isn’t constant. The Emacs Lisp evaluator evaluates the argument of ‘,’, and puts the value in the list structure:
`(a list of ,(+ 2 3) elements)
⇒ (a list of 5 elements)
Substitution with ‘,’ is allowed at deeper levels of the list structure also. For example:
`(1 2 (3 ,(+ 4 5)))
⇒ (1 2 (3 9))
You can also splice an evaluated value into the resulting list, using the special marker ‘,@’. The elements of the spliced list become elements at the same level as the other elements of the resulting list. The equivalent code without using ‘`’ is often unreadable. Here are some examples:
(setq some-list '(2 3))
⇒ (2 3)
(cons 1 (append some-list '(4) some-list))
⇒ (1 2 3 4 2 3)
`(1 ,@some-list 4 ,@some-list)
⇒ (1 2 3 4 2 3)
(setq list '(hack foo bar))
⇒ (hack foo bar)
(cons 'use
(cons 'the
(cons 'words (append (cdr list) '(as elements)))))
⇒ (use the words foo bar as elements)
`(use the words ,@(cdr list) as elements)
⇒ (use the words foo bar as elements)
A backquote construct acts like quote in that it yields conses,
vectors and strings that might be shared and should not be modified.
See Self-Evaluating Forms.
Most often, forms are evaluated automatically, by virtue of their
occurrence in a program being run. On rare occasions, you may need to
write code that evaluates a form that is computed at run time, such as
after reading a form from text being edited or getting one from a
property list. On these occasions, use the eval function.
Often eval is not needed and something else should be used instead.
For example, to get the value of a variable, while eval works,
symbol-value is preferable; or rather than store expressions
in a property list that then need to go through eval, it is better to
store functions instead that are then passed to funcall.
The functions and variables described in this section evaluate forms, specify limits to the evaluation process, or record recently returned values. Loading a file also does evaluation (see Loading).
It is generally cleaner and more flexible to store a function in a
data structure, and call it with funcall or apply, than
to store an expression in the data structure and evaluate it. Using
functions provides the ability to pass information to them as
arguments.
This is the basic function for evaluating an expression. It evaluates form in the current environment, and returns the result. The type of the form object determines how it is evaluated. See Kinds of Forms.
The argument lexical specifies the scoping rule for local
variables (see Scoping Rules for Variable Bindings). If it is t, that means
to evaluate form using lexical scoping; this is the recommended
value. If it is omitted or nil, that means to use the old
dynamic-only variable scoping rule.
The value of lexical can also be a non-empty list specifying a particular lexical environment for lexical bindings; however, this feature is only useful for specialized purposes, such as in Emacs Lisp debuggers. Each member of the list is either a cons cell which represents a lexical symbol-value pair, or a symbol representing a (special) variable that would use dynamic scoping if bound.
Since eval is a function, the argument expression that appears
in a call to eval is evaluated twice: once as preparation before
eval is called, and again by the eval function itself.
Here is an example:
(setq foo 'bar)
⇒ bar
(setq bar 'baz)
⇒ baz
;; Here eval receives argument foo
(eval 'foo)
⇒ bar
;; Here eval receives argument bar, which is the value of foo
(eval foo)
⇒ baz
The number of currently active calls to eval is limited to
max-lisp-eval-depth (see below).
This function evaluates the forms in the current buffer in the region
defined by the positions start and end. It reads forms from
the region and calls eval on them until the end of the region is
reached, or until an error is signaled and not handled.
By default, eval-region does not produce any output. However,
if stream is non-nil, any output produced by output
functions (see Output Functions), as well as the values that
result from evaluating the expressions in the region are printed using
stream. See Output Streams.
If read-function is non-nil, it should be a function,
which is used instead of read to read expressions one by one.
This function is called with one argument, the stream for reading
input. You can also use the variable load-read-function
(see How Programs Do Loading)
to specify this function, but it is more robust to use the
read-function argument.
eval-region does not move point. It always returns nil.
This is similar to eval-region, but the arguments provide
different optional features. eval-buffer operates on the
entire accessible portion of buffer buffer-or-name
(see Narrowing in The GNU Emacs Manual).
buffer-or-name can be a buffer, a buffer name (a string), or
nil (or omitted), which means to use the current buffer.
stream is used as in eval-region, unless stream is
nil and print non-nil. In that case, values that
result from evaluating the expressions are still discarded, but the
output of the output functions is printed in the echo area.
filename is the file name to use for load-history
(see Unloading), and defaults to buffer-file-name
(see Buffer File Name). If unibyte is non-nil,
read converts strings to unibyte whenever possible.
This variable defines the maximum depth allowed in calls to eval,
apply, and funcall before an error is signaled (with error
message "Lisp nesting exceeds max-lisp-eval-depth").
This limit, with the associated error when it is exceeded, is how
Emacs Lisp avoids infinite recursion on an ill-defined function. If
you increase the value of max-lisp-eval-depth too much, such
code can cause stack overflow instead. On some systems, this overflow
can be handled. In that case, normal Lisp evaluation is interrupted
and control is transferred back to the top level command loop
(top-level). Note that there is no way to enter Emacs Lisp
debugger in this situation. See Entering the Debugger on an Error.
The depth limit counts internal uses of eval, apply, and
funcall, such as for calling the functions mentioned in Lisp
expressions, and recursive evaluation of function call arguments and
function body forms, as well as explicit calls in Lisp code.
The default value of this variable is 1600. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached.
In order to be able to debug infinite recursion errors, when invoking the
Lisp debugger, Emacs increases temporarily the value of
max-lisp-eval-depth, if there is little room left, to make sure
the debugger itself has room to execute. The same happens when
running the handler of a handler-bind. See Writing Code to Handle Errors.
The variable lisp-eval-depth-reserve bounds the extra depth
that Emacs can add to max-lisp-eval-depth for those
exceptional circumstances.
The default value of this variable is 200.
The value of this variable is a list of the values returned by all the
expressions that were read, evaluated, and printed from buffers
(including the minibuffer) by the standard Emacs commands which do
this. (Note that this does not include evaluation in
*ielm* buffers, nor evaluation using C-j, C-x C-e,
and similar evaluation commands in lisp-interaction-mode.)
This variable is obsolete, and will be removed in a future version, since it constantly enlarges the memory footprint of the Emacs process. For that reason, we recommend against using it.
The elements of values are ordered most recent first.
(setq x 1)
⇒ 1
(list 'A (1+ 2) auto-save-default)
⇒ (A 3 t)
values
⇒ ((A 3 t) 1 ...)
This variable could be useful for referring back to values of forms
recently evaluated. It is generally a bad idea to print the value of
values itself, since this may be very long. Instead, examine
particular elements, like this:
;; Refer to the most recent evaluation result.
(nth 0 values)
⇒ (A 3 t)
;; That put a new element on, ;; so all elements move back one. (nth 1 values) ⇒ (A 3 t)
;; This gets the element that was next-to-most-recent ;; before this example. (nth 3 values) ⇒ 1
Sometimes it is useful to delay the evaluation of an expression, for example if you want to avoid performing a time-consuming calculation if it turns out that the result is not needed in the future of the program. The thunk library provides the following functions and macros to support such deferred evaluation:
Return a thunk for evaluating the forms. A thunk is a
closure (see Closures) that inherits the lexical environment of the
thunk-delay call. Using this macro requires
lexical-binding.
Force thunk to perform the evaluation of the forms specified in
the thunk-delay that created the thunk. The result of the
evaluation of the last form is returned. The thunk also
“remembers” that it has been forced: Any further calls of
thunk-force with the same thunk will just return the same
result without evaluating the forms again.
This macro is analogous to let but creates “lazy” variable
bindings. Any binding has the form (symbol value-form). Unlike let, the evaluation of any
value-form is deferred until the binding of the according
symbol is used for the first time when evaluating the
forms. Any value-form is evaluated at most once. Using
this macro requires lexical-binding.
Example:
(defun f (number)
(thunk-let ((derived-number
(progn (message "Calculating 1 plus 2 times %d" number)
(1+ (* 2 number)))))
(if (> number 10)
derived-number
number)))
(f 5) ⇒ 5
(f 12) ⊣ Calculating 1 plus 2 times 12 ⇒ 25
Because of the special nature of lazily bound variables, it is an error
to set them (e.g. with setq).
This is like thunk-let but any expression in bindings is allowed
to refer to preceding bindings in this thunk-let* form. Using
this macro requires lexical-binding.
(thunk-let* ((x (prog2 (message "Calculating x...")
(+ 1 1)
(message "Finished calculating x")))
(y (prog2 (message "Calculating y...")
(+ x 1)
(message "Finished calculating y")))
(z (prog2 (message "Calculating z...")
(+ y 1)
(message "Finished calculating z")))
(a (prog2 (message "Calculating a...")
(+ z 1)
(message "Finished calculating a"))))
(* z x))
⊣ Calculating z...
⊣ Calculating y...
⊣ Calculating x...
⊣ Finished calculating x
⊣ Finished calculating y
⊣ Finished calculating z
⇒ 8
thunk-let and thunk-let* use thunks implicitly: their
expansion creates helper symbols and binds them to thunks wrapping the
binding expressions. All references to the original variables in the
body forms are then replaced by an expression that calls
thunk-force with the according helper variable as the argument.
So, any code using thunk-let or thunk-let* could be
rewritten to use thunks, but in many cases using these macros results
in nicer code than using thunks explicitly.
It is sometimes also referred to as an S-expression or sexp, but we generally do not use this terminology in this manual.
This definition of “environment” is specifically not intended to include all the data that can affect the result of a program.