[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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. The value is computed in
a fashion that depends on the data type of the object, following 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 which 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. @xref{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.
@xref{Command Loop}.
Evaluation is a recursive process. That is, evaluation of a form may
cause eval
to be called again in order 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
.
The evaluation of forms takes place in a context called the environment, which consists of the current values and bindings of all Lisp variables.(1) Whenever the form refers to a variable without creating a new binding for it, the value of the binding in the current environment is used. @xref{Variables}.
Evaluation of a form may create new environments for recursive
evaluation by binding variables (@pxref{Local Variables}). These
environments are temporary and will be gone 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)
.
Finally, evaluation of one particular function call, byte-code
,
invokes the byte-code interpreter on its arguments. Although the
byte-code interpreter is not the same as the Lisp interpreter, it uses
the same environment as the Lisp interpreter, and may on occasion invoke
the Lisp interpreter. (@xref{Byte Compilation}.)
The details of what evaluation means for each kind of form are described below (see section Kinds of Forms).
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 (@pxref{Loading}).
This is the basic function for performing evaluation. It evaluates form in the current environment and returns the result. How the evaluation proceeds depends on the type of the object (see section Kinds of Forms).
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
;; 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. It reads
forms from the buffer and calls eval
on them until the end of the
buffer is reached, or until an error is signaled and not handled.
If stream is supplied, the variable standard-output
is
bound to stream during the evaluation (@pxref{Output
Functions}).
eval-current-buffer
always returns nil
.
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.
If stream is supplied, standard-output
is bound to it
for the duration of the command.
eval-region
always returns nil
.
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"
). eval
is called recursively to evaluate
the arguments of Lisp function calls and to evaluate bodies of
functions.
This limit, with the associated error when it is exceeded, is one way that Lisp avoids infinite recursion on an ill-defined function.
The default value of this variable is 200. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached.
max-specpdl-size
provides another limit on nesting.
@xref{Local Variables}.
The value of this variable is a list of values returned by all expressions which were read from buffers (including the minibuffer), evaluated, and printed. The elements are in order, most recent first.
(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-last ;; before this example. (nth 3 values) ⇒ 1
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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”. All three kinds are described in this section, starting with “all other types” which are self-evaluating forms.
1.2.1 Self-Evaluating Forms | Forms that evaluate to themselves. | |
1.2.2 Symbol Forms | Symbols evaluate as variables. | |
1.2.3 Classification of List Forms | How to distinguish various sorts of list forms. | |
1.2.4 Symbol Function Indirection | When a symbol appears as the car of a list, we find the real function via the symbol. | |
1.2.5 Evaluation of Function Forms | Forms that call functions. | |
1.2.6 Lisp Macro Evaluation | Forms that call macros. | |
1.2.7 Special Forms | “Special forms” are idiosyncratic primitives, most of them extremely important. | |
1.2.8 Autoloading | Functions set up to load files containing their real definitions. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 ; An object, 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 it is inconvenient and not very useful; however, it is possible to put them inside Lisp programs when they are constructed from subexpressions rather than read. Here is an example:
;; Build such an expression.
(setq buffer (list 'print (current-buffer)))
⇒ (print #<buffer eval.texi>)
;; Evaluate it.
(eval buffer)
-| #<buffer eval.texi>
⇒ #<buffer eval.texi>
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 @ref{Variables}.
In the following example, we set the value of a symbol with
setq
. When the symbol is later evaluated, that value is
returned.
(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
. Thus, these two symbols act like self-evaluating
forms, even though eval
treats them like any other symbol.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 rest of the list consists of 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 including Scheme.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 a non-symbol is obtained. @xref{Function Names}, 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, causing 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
(@pxref{Function Cells}). 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
After that function is called, its body is evaluated; 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.
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.
Here is how you could define indirect-function
in Lisp:
(defun indirect-function (function) (if (symbolp function) (indirect-function (symbol-function function)) function))
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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)
When a function call is evaluated, the first step is to evaluate the
remaining elements of the list in the order they appear. The results
are the actual argument values, one argument from each element. Then
the function is called with this list of arguments, effectively using
the function apply
(@pxref{Calling Functions}). If the function
is written in Lisp, the arguments are used to bind the argument
variables of the function (@pxref{Lambda Expressions}); then the forms
in the function body are evaluated in order, and the result of the last
one is used as the value of the function call.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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, which is 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.
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 evaluated 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.
@xref{Macros}, for a complete description of Emacs Lisp macros.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A special form is a primitive function specially marked so that its arguments are not all evaluated. 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.
and
@pxref{Combining Conditions}
catch
@pxref{Catch and Throw}
cond
@pxref{Conditionals}
condition-case
@pxref{Handling Errors}
defconst
@pxref{Defining Variables}
defmacro
@pxref{Defining Macros}
defun
@pxref{Defining Functions}
defvar
@pxref{Defining Variables}
function
@pxref{Anonymous Functions}
if
@pxref{Conditionals}
interactive
@pxref{Interactive Call}
let
let*
@pxref{Local Variables}
or
@pxref{Combining Conditions}
prog1
prog2
progn
@pxref{Sequencing}
quote
see section Quoting
save-excursion
@pxref{Excursions}
save-restriction
@pxref{Narrowing}
save-window-excursion
@pxref{Window Configurations}
setq
@pxref{Setting Variables}
setq-default
@pxref{Creating Buffer-Local}
track-mouse
@pxref{Mouse Tracking}
unwind-protect
@pxref{Nonlocal Exits}
while
@pxref{Iteration}
with-output-to-temp-buffer
@pxref{Temporary Displays}
Common Lisp note: here are some comparisons of special forms in GNU Emacs Lisp and Common Lisp.
setq
,if
, andcatch
are special forms in both Emacs Lisp and Common Lisp.defun
is a special form in Emacs Lisp, but a macro in Common Lisp.save-excursion
is a special form in Emacs Lisp, but doesn’t exist in Common Lisp.throw
is 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).
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The autoload feature allows you to call a function or macro whose function definition has not yet been loaded into Emacs. When an autoload object appears as a symbol’s function definition and that symbol is used as a function, Emacs will automatically install the real definition (plus other associated code) and then call that definition. (@xref{Autoload}.)
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The special form quote
returns its single argument
“unchanged”.
This special form returns object, without evaluating it. This allows symbols and lists, which would normally be evaluated, to be included literally in a program. (It is not necessary to quote numbers, strings, and vectors since they are self-evaluating.)
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
(@pxref{Anonymous
Functions}), which causes an anonymous lambda expression written in Lisp
to be compiled, and `
(@pxref{Backquote}), which is used to quote
only part of a list, while computing and substituting other parts.
[Top] | [Contents] | [Index] | [ ? ] |
This definition of “environment” is specifically not intended to include all the data which can affect the result of a program.
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on January 16, 2023 using texi2html 5.0.
The buttons in the navigation panels have the following meaning:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
[ < ] | Back | Previous section in reading order | 1.2.2 |
[ Up ] | Up | Up section | 1.2 |
[ > ] | Forward | Next section in reading order | 1.2.4 |
[ >> ] | FastForward | Next chapter | 2 |
[Top] | Top | Cover (top) of document | |
[Contents] | Contents | Table of contents | |
[Index] | Index | Index | |
[ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on January 16, 2023 using texi2html 5.0.