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.
A Lisp object that is intended for evaluation is called an expression or a form. The fact that expressions 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.
It is very common to read a Lisp expression and then evaluate
the expression, 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
whether this object is a form to be evaluated, or serves some
entirely different purpose. See section Input Functions.
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 invoke the command. The
execution of the command itself involves evaluation if the command
is written in Lisp, but that is not a part of command key
interpretation itself. See section Command Loop.
Evaluation is a recursive
process. That is, evaluation of a form may call eval
to evaluate parts of the form. For example, evaluation of a
function call first evaluates each argument of the function call,
and then evaluates each form in the function body. Consider
evaluation of the form (car x): the subform
x must first be evaluated recursively, so that its
value can be passed as an argument to the function
car.
Evaluation of a function call ultimately calls the function specified in it. See section Functions. The execution of the function may itself work by evaluating the function definition; or the function may be a Lisp primitive implemented in C, or it may be a byte-compiled function (see section Byte Compilation).
The evaluation of forms takes place in a context called the environment, which consists of the current values and bindings of all Lisp variables.(2) Whenever a form refers to a variable without creating a new binding for it, the value of the variable's binding in the current environment is used. See section Variables.
Evaluation of a form may
create new environments for recursive evaluation by binding
variables (see section Local
Variables). These environments are temporary and vanish by the
time evaluation of the form is complete. The form may also make
changes that persist; these changes are called side
effects. An example of a form that produces side effects is
(setq foo 1).
The details of what evaluation means for each kind of form are described below (see section Kinds of Forms).
A Lisp object that is intended to be evaluated is called a form. 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 "all 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, evaluation of
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
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 it has none (if its value cell is void), an error is signaled. For more information on the use of variables, see section 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 section
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 section Naming a Function, for more information about using a symbol as a name for a function stored in the function cell of the symbol.
One possible consequence of this process is an infinite loop, in
the event that a symbol's function cell refers to the same symbol.
Or a symbol may have a void function cell, in which case the
subroutine symbol-function signals a
void-function error. But if neither of these things
happens, 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, the error
invalid-function is signaled.
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 section 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.
The built-in function indirect-function provides an
easy way to perform symbol function indirection explicitly.
Here is how you could define indirect-function in
Lisp:
(defun indirect-function (function)
(if (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 section Calling Functions). If the function is
written in Lisp, the arguments are used to bind the argument
variables of the function (see section 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 section Macros, for a complete description of Emacs Lisp macros.
A special form is a primitive function 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.
Here is a list, in alphabetical order, of all of the special forms in Emacs Lisp with a reference to where each is described.
andcatchcondcondition-casedefconstdefmacrodefundefvarfunctionifinteractiveletlet*orprog1prog2prognquotesave-current-buffersave-excursionsave-restrictionsave-window-excursionsetqsetq-defaulttrack-mouseunwind-protectwhilewith-output-to-temp-bufferCommon 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.defunis a special form in Emacs Lisp, but a macro in 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. See section 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.)
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
=> (quote foo)
'(quote foo)
=> (quote foo)
['foo]
=> [(quote foo)]
Other quoting constructs include function (see
section Anonymous Functions), which
causes an anonymous lambda expression written in Lisp to be
compiled, and ``' (see section Backquote), which is used to quote
only part of a list, while computing and substituting other
parts.
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.
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 section Loading).
Note: 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.
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).
eval on them until the end of the region is
reached, or until an error is signaled and not handled. If stream is non-nil, the values that
result from evaluating the expressions in the region are printed
using stream. See section 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 section How Programs Do Loading) to specify
this function, but it is more robust to use the
read-function argument.
eval-region always returns nil.
eval-region except that it operates on the whole
buffer.
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 one way that Lisp avoids infinite recursion
on an ill-defined function.
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 300. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to execute.
max-specpdl-size provides another limit on nesting.
See section Local Variables.
(setq x 1)
=> 1
(list 'A (1+ 2) auto-save-default)
=> (A 3 t)
values
=> ((A 3 t) 1 ...)
This variable is 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