2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/eval
6 @node Evaluation, Control Structures, Symbols, Top
11 @cindex value of expression
13 The @dfn{evaluation} of expressions in Emacs Lisp is performed by the
14 @dfn{Lisp interpreter}---a program that receives a Lisp object as input
15 and computes its @dfn{value as an expression}. How it does this depends
16 on the data type of the object, according to rules described in this
17 chapter. The interpreter runs automatically to evaluate portions of
18 your program, but can also be called explicitly via the Lisp primitive
23 * Intro Eval:: Evaluation in the scheme of things.
24 * Eval:: How to invoke the Lisp interpreter explicitly.
25 * Forms:: How various sorts of objects are evaluated.
26 * Quoting:: Avoiding evaluation (to put constants in the program).
30 @section Introduction to Evaluation
32 The Lisp interpreter, or evaluator, is the program that computes
33 the value of an expression that is given to it. When a function
34 written in Lisp is called, the evaluator computes the value of the
35 function by evaluating the expressions in the function body. Thus,
36 running any Lisp program really means running the Lisp interpreter.
38 How the evaluator handles an object depends primarily on the data
44 A Lisp object that is intended for evaluation is called an
45 @dfn{expression} or a @dfn{form}. The fact that expressions are data
46 objects and not merely text is one of the fundamental differences
47 between Lisp-like languages and typical programming languages. Any
48 object can be evaluated, but in practice only numbers, symbols, lists
49 and strings are evaluated very often.
51 It is very common to read a Lisp expression and then evaluate the
52 expression, but reading and evaluation are separate activities, and
53 either can be performed alone. Reading per se does not evaluate
54 anything; it converts the printed representation of a Lisp object to the
55 object itself. It is up to the caller of @code{read} whether this
56 object is a form to be evaluated, or serves some entirely different
57 purpose. @xref{Input Functions}.
59 Do not confuse evaluation with command key interpretation. The
60 editor command loop translates keyboard input into a command (an
61 interactively callable function) using the active keymaps, and then
62 uses @code{call-interactively} to invoke the command. The execution of
63 the command itself involves evaluation if the command is written in
64 Lisp, but that is not a part of command key interpretation itself.
67 @cindex recursive evaluation
68 Evaluation is a recursive process. That is, evaluation of a form may
69 call @code{eval} to evaluate parts of the form. For example, evaluation
70 of a function call first evaluates each argument of the function call,
71 and then evaluates each form in the function body. Consider evaluation
72 of the form @code{(car x)}: the subform @code{x} must first be evaluated
73 recursively, so that its value can be passed as an argument to the
77 The evaluation of forms takes place in a context called the
78 @dfn{environment}, which consists of the current values and bindings of
79 all Lisp variables.@footnote{This definition of ``environment'' is
80 specifically not intended to include all the data that can affect the
81 result of a program.} Whenever the form refers to a variable without
82 creating a new binding for it, the value of the binding in the current
83 environment is used. @xref{Variables}.
86 Evaluation of a form may create new environments for recursive
87 evaluation by binding variables (@pxref{Local Variables}). These
88 environments are temporary and vanish by the time evaluation of the form
89 is complete. The form may also make changes that persist; these changes
90 are called @dfn{side effects}. An example of a form that produces side
91 effects is @code{(setq foo 1)}.
93 Finally, evaluation of one particular function call, @code{byte-code},
94 invokes the @dfn{byte-code interpreter} on its arguments. Although the
95 byte-code interpreter is not the same as the Lisp interpreter, it uses
96 the same environment as the Lisp interpreter, and may on occasion invoke
97 the Lisp interpreter. (@xref{Byte Compilation}.)
99 The details of what evaluation means for each kind of form are
100 described below (@pxref{Forms}).
105 Most often, forms are evaluated automatically, by virtue of their
106 occurrence in a program being run. On rare occasions, you may need to
107 write code that evaluates a form that is computed at run time, such as
108 after reading a form from text being edited or getting one from a
109 property list. On these occasions, use the @code{eval} function.
111 The functions and variables described in this section evaluate
112 forms, specify limits to the evaluation process, or record recently
113 returned values. Loading a file also does evaluation
117 This is the basic function for performing evaluation. It evaluates
118 @var{form} in the current environment and returns the result. How the
119 evaluation proceeds depends on the type of the object (@pxref{Forms}).
121 Since @code{eval} is a function, the argument expression that appears
122 in a call to @code{eval} is evaluated twice: once as preparation before
123 @code{eval} is called, and again by the @code{eval} function itself.
134 ;; @r{@code{eval} receives argument @code{bar}, which is the value of @code{foo}}
142 The number of currently active calls to @code{eval} is limited to
143 @code{max-lisp-eval-depth} (see below).
146 @cindex evaluation of buffer contents
147 @deffn Command eval-current-buffer &optional stream
148 This function evaluates the forms in the current buffer. It reads
149 forms from the buffer and calls @code{eval} on them until the end of the
150 buffer is reached, or until an error is signaled and not handled.
152 If @var{stream} is supplied, the variable @code{standard-output} is
153 bound to @var{stream} during the evaluation (@pxref{Output
156 @code{eval-current-buffer} always returns @code{nil}.
159 @deffn Command eval-region start end &optional stream
160 This function evaluates the forms in the current buffer in the region
161 defined by the positions @var{start} and @var{end}. It reads forms from
162 the region and calls @code{eval} on them until the end of the region is
163 reached, or until an error is signaled and not handled.
165 If @var{stream} is supplied, @code{standard-output} is bound to it
166 during the evaluation.
168 You can use the variable @code{load-read-function} to specify a function
169 for @code{eval-region} to use instead of @code{read} for reading
170 expressions. @xref{How Programs Do Loading}.
172 @code{eval-region} always returns @code{nil}.
175 @defvar max-lisp-eval-depth
176 This variable defines the maximum depth allowed in calls to @code{eval},
177 @code{apply}, and @code{funcall} before an error is signaled (with error
178 message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This counts
179 internal uses of those functions, such as for calling the functions
180 mentioned in Lisp expressions, and recursive evaluation of function call
181 arguments and function body forms.
183 This limit, with the associated error when it is exceeded, is one way
184 that Lisp avoids infinite recursion on an ill-defined function.
185 @cindex Lisp nesting error
187 The default value of this variable is 200. If you set it to a value
188 less than 100, Lisp will reset it to 100 if the given value is reached.
190 @code{max-specpdl-size} provides another limit on nesting.
191 @xref{Local Variables}.
195 The value of this variable is a list of the values returned by all the
196 expressions that were read from buffers (including the minibuffer),
197 evaluated, and printed. The elements are ordered most recent first.
205 (list 'A (1+ 2) auto-save-default)
210 @result{} ((A 3 t) 1 @dots{})
214 This variable is useful for referring back to values of forms recently
215 evaluated. It is generally a bad idea to print the value of
216 @code{values} itself, since this may be very long. Instead, examine
217 particular elements, like this:
221 ;; @r{Refer to the most recent evaluation result.}
226 ;; @r{That put a new element on,}
227 ;; @r{so all elements move back one.}
232 ;; @r{This gets the element that was next-to-most-recent}
233 ;; @r{before this example.}
241 @section Kinds of Forms
243 A Lisp object that is intended to be evaluated is called a @dfn{form}.
244 How Emacs evaluates a form depends on its data type. Emacs has three
245 different kinds of form that are evaluated differently: symbols, lists,
246 and ``all other types''. This section describes all three kinds,
247 starting with ``all other types'' which are self-evaluating forms.
250 * Self-Evaluating Forms:: Forms that evaluate to themselves.
251 * Symbol Forms:: Symbols evaluate as variables.
252 * Classifying Lists:: How to distinguish various sorts of list forms.
253 * Function Indirection:: When a symbol appears as the car of a list,
254 we find the real function via the symbol.
255 * Function Forms:: Forms that call functions.
256 * Macro Forms:: Forms that call macros.
257 * Special Forms:: ``Special forms'' are idiosyncratic primitives,
258 most of them extremely important.
259 * Autoloading:: Functions set up to load files
260 containing their real definitions.
263 @node Self-Evaluating Forms
264 @subsection Self-Evaluating Forms
265 @cindex vector evaluation
266 @cindex literal evaluation
267 @cindex self-evaluating form
269 A @dfn{self-evaluating form} is any form that is not a list or symbol.
270 Self-evaluating forms evaluate to themselves: the result of evaluation
271 is the same object that was evaluated. Thus, the number 25 evaluates to
272 25, and the string @code{"foo"} evaluates to the string @code{"foo"}.
273 Likewise, evaluation of a vector does not cause evaluation of the
274 elements of the vector---it returns the same vector with its contents
279 '123 ; @r{An object, shown without evaluation.}
283 123 ; @r{Evaluated as usual---result is the same.}
287 (eval '123) ; @r{Evaluated ``by hand''---result is the same.}
291 (eval (eval '123)) ; @r{Evaluating twice changes nothing.}
296 It is common to write numbers, characters, strings, and even vectors
297 in Lisp code, taking advantage of the fact that they self-evaluate.
298 However, it is quite unusual to do this for types that lack a read
299 syntax, because there's no way to write them textually; however, it is
300 possible to construct Lisp expressions containing these types by means
301 of a Lisp program. Here is an example:
305 ;; @r{Build an expression containing a buffer object.}
306 (setq buffer (list 'print (current-buffer)))
307 @result{} (print #<buffer eval.texi>)
312 @print{} #<buffer eval.texi>
313 @result{} #<buffer eval.texi>
318 @subsection Symbol Forms
319 @cindex symbol evaluation
321 When a symbol is evaluated, it is treated as a variable. The result
322 is the variable's value, if it has one. If it has none (if its value
323 cell is void), an error is signaled. For more information on the use of
324 variables, see @ref{Variables}.
326 In the following example, we set the value of a symbol with
327 @code{setq}. Then we evaluate the symbol, and get back the value that
345 The symbols @code{nil} and @code{t} are treated specially, so that the
346 value of @code{nil} is always @code{nil}, and the value of @code{t} is
347 always @code{t}; you cannot set or bind them to any other values. Thus,
348 these two symbols act like self-evaluating forms, even though
349 @code{eval} treats them like any other symbol.
351 @node Classifying Lists
352 @subsection Classification of List Forms
353 @cindex list form evaluation
355 A form that is a nonempty list is either a function call, a macro
356 call, or a special form, according to its first element. These three
357 kinds of forms are evaluated in different ways, described below. The
358 remaining list elements constitute the @dfn{arguments} for the function,
359 macro, or special form.
361 The first step in evaluating a nonempty list is to examine its first
362 element. This element alone determines what kind of form the list is
363 and how the rest of the list is to be processed. The first element is
364 @emph{not} evaluated, as it would be in some Lisp dialects such as
367 @node Function Indirection
368 @subsection Symbol Function Indirection
369 @cindex symbol function indirection
371 @cindex void function
373 If the first element of the list is a symbol then evaluation examines
374 the symbol's function cell, and uses its contents instead of the
375 original symbol. If the contents are another symbol, this process,
376 called @dfn{symbol function indirection}, is repeated until it obtains a
377 non-symbol. @xref{Function Names}, for more information about using a
378 symbol as a name for a function stored in the function cell of the
381 One possible consequence of this process is an infinite loop, in the
382 event that a symbol's function cell refers to the same symbol. Or a
383 symbol may have a void function cell, in which case the subroutine
384 @code{symbol-function} signals a @code{void-function} error. But if
385 neither of these things happens, we eventually obtain a non-symbol,
386 which ought to be a function or other suitable object.
388 @kindex invalid-function
389 @cindex invalid function
390 More precisely, we should now have a Lisp function (a lambda
391 expression), a byte-code function, a primitive function, a Lisp macro, a
392 special form, or an autoload object. Each of these types is a case
393 described in one of the following sections. If the object is not one of
394 these types, the error @code{invalid-function} is signaled.
396 The following example illustrates the symbol indirection process. We
397 use @code{fset} to set the function cell of a symbol and
398 @code{symbol-function} to get the function cell contents
399 (@pxref{Function Cells}). Specifically, we store the symbol @code{car}
400 into the function cell of @code{first}, and the symbol @code{first} into
401 the function cell of @code{erste}.
405 ;; @r{Build this function cell linkage:}
406 ;; ------------- ----- ------- -------
407 ;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
408 ;; ------------- ----- ------- -------
414 (symbol-function 'car)
415 @result{} #<subr car>
426 (erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.}
431 By contrast, the following example calls a function without any symbol
432 function indirection, because the first element is an anonymous Lisp
433 function, not a symbol.
437 ((lambda (arg) (erste arg))
444 Executing the function itself evaluates its body; this does involve
445 symbol function indirection when calling @code{erste}.
447 The built-in function @code{indirect-function} provides an easy way to
448 perform symbol function indirection explicitly.
451 @defun indirect-function function
452 This function returns the meaning of @var{function} as a function. If
453 @var{function} is a symbol, then it finds @var{function}'s function
454 definition and starts over with that value. If @var{function} is not a
455 symbol, then it returns @var{function} itself.
457 Here is how you could define @code{indirect-function} in Lisp:
460 (defun indirect-function (function)
461 (if (symbolp function)
462 (indirect-function (symbol-function function))
468 @subsection Evaluation of Function Forms
469 @cindex function form evaluation
470 @cindex function call
472 If the first element of a list being evaluated is a Lisp function
473 object, byte-code object or primitive function object, then that list is
474 a @dfn{function call}. For example, here is a call to the function
481 The first step in evaluating a function call is to evaluate the
482 remaining elements of the list from left to right. The results are the
483 actual argument values, one value for each list element. The next step
484 is to call the function with this list of arguments, effectively using
485 the function @code{apply} (@pxref{Calling Functions}). If the function
486 is written in Lisp, the arguments are used to bind the argument
487 variables of the function (@pxref{Lambda Expressions}); then the forms
488 in the function body are evaluated in order, and the value of the last
489 body form becomes the value of the function call.
492 @subsection Lisp Macro Evaluation
493 @cindex macro call evaluation
495 If the first element of a list being evaluated is a macro object, then
496 the list is a @dfn{macro call}. When a macro call is evaluated, the
497 elements of the rest of the list are @emph{not} initially evaluated.
498 Instead, these elements themselves are used as the arguments of the
499 macro. The macro definition computes a replacement form, called the
500 @dfn{expansion} of the macro, to be evaluated in place of the original
501 form. The expansion may be any sort of form: a self-evaluating
502 constant, a symbol, or a list. If the expansion is itself a macro call,
503 this process of expansion repeats until some other sort of form results.
505 Ordinary evaluation of a macro call finishes by evaluating the
506 expansion. However, the macro expansion is not necessarily evaluated
507 right away, or at all, because other programs also expand macro calls,
508 and they may or may not evaluate the expansions.
510 Normally, the argument expressions are not evaluated as part of
511 computing the macro expansion, but instead appear as part of the
512 expansion, so they are computed when the expansion is computed.
514 For example, given a macro defined as follows:
519 (list 'car (list 'cdr x)))
524 an expression such as @code{(cadr (assq 'handler list))} is a macro
525 call, and its expansion is:
528 (car (cdr (assq 'handler list)))
532 Note that the argument @code{(assq 'handler list)} appears in the
535 @xref{Macros}, for a complete description of Emacs Lisp macros.
538 @subsection Special Forms
539 @cindex special form evaluation
541 A @dfn{special form} is a primitive function specially marked so that
542 its arguments are not all evaluated. Most special forms define control
543 structures or perform variable bindings---things which functions cannot
546 Each special form has its own rules for which arguments are evaluated
547 and which are used without evaluation. Whether a particular argument is
548 evaluated may depend on the results of evaluating other arguments.
550 Here is a list, in alphabetical order, of all of the special forms in
551 Emacs Lisp with a reference to where each is described.
555 @pxref{Combining Conditions}
558 @pxref{Catch and Throw}
564 @pxref{Handling Errors}
567 @pxref{Defining Variables}
570 @pxref{Defining Macros}
573 @pxref{Defining Functions}
576 @pxref{Defining Variables}
579 @pxref{Anonymous Functions}
585 @pxref{Interactive Call}
589 @pxref{Local Variables}
592 @pxref{Combining Conditions}
605 @item save-restriction
608 @item save-window-excursion
609 @pxref{Window Configurations}
612 @pxref{Setting Variables}
615 @pxref{Creating Buffer-Local}
618 @pxref{Mouse Tracking}
621 @pxref{Nonlocal Exits}
626 @item with-output-to-temp-buffer
627 @pxref{Temporary Displays}
630 @cindex CL note---special forms compared
632 @b{Common Lisp note:} Here are some comparisons of special forms in
633 GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and
634 @code{catch} are special forms in both Emacs Lisp and Common Lisp.
635 @code{defun} is a special form in Emacs Lisp, but a macro in Common
636 Lisp. @code{save-excursion} is a special form in Emacs Lisp, but
637 doesn't exist in Common Lisp. @code{throw} is a special form in
638 Common Lisp (because it must be able to throw multiple values), but it
639 is a function in Emacs Lisp (which doesn't have multiple
644 @subsection Autoloading
646 The @dfn{autoload} feature allows you to call a function or macro
647 whose function definition has not yet been loaded into Emacs. It
648 specifies which file contains the definition. When an autoload object
649 appears as a symbol's function definition, calling that symbol as a
650 function automatically loads the specified file; then it calls the real
651 definition loaded from that file. @xref{Autoload}.
657 The special form @code{quote} returns its single argument
660 @defspec quote object
661 This special form returns @var{object}, without evaluating it. This
662 provides a way to include constant symbols and lists, which are not
663 self-evaluating objects, in a program. (It is not necessary to quote
664 self-evaluating objects such as numbers, strings, and vectors.)
666 @cindex @samp{'} for quoting
667 @cindex quoting using apostrophe
668 @cindex apostrophe for quoting
669 Because @code{quote} is used so often in programs, Lisp provides a
670 convenient read syntax for it. An apostrophe character (@samp{'})
671 followed by a Lisp object (in read syntax) expands to a list whose first
672 element is @code{quote}, and whose second element is the object. Thus,
673 the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
675 Here are some examples of expressions that use @code{quote}:
692 @result{} (quote foo)
696 @result{} (quote foo)
700 @result{} [(quote foo)]
705 Other quoting constructs include @code{function} (@pxref{Anonymous
706 Functions}), which causes an anonymous lambda expression written in Lisp
707 to be compiled, and @code{`} (@pxref{Backquote}), which is used to quote
708 only part of a list, while computing and substituting other parts.