2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 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 * Forms:: How various sorts of objects are evaluated.
25 * Quoting:: Avoiding evaluation (to put constants in the program).
26 * Eval:: How to invoke the Lisp interpreter explicitly.
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
76 Evaluation of a function call ultimately calls the function specified
77 in it. @xref{Functions}. The execution of the function may itself work
78 by evaluating the function definition; or the function may be a Lisp
79 primitive implemented in C, or it may be a byte-compiled function
80 (@pxref{Byte Compilation}).
83 The evaluation of forms takes place in a context called the
84 @dfn{environment}, which consists of the current values and bindings of
85 all Lisp variables.@footnote{This definition of ``environment'' is
86 specifically not intended to include all the data that can affect the
87 result of a program.} Whenever a form refers to a variable without
88 creating a new binding for it, the value of the variable's binding in
89 the current environment is used. @xref{Variables}.
92 Evaluation of a form may create new environments for recursive
93 evaluation by binding variables (@pxref{Local Variables}). These
94 environments are temporary and vanish by the time evaluation of the form
95 is complete. The form may also make changes that persist; these changes
96 are called @dfn{side effects}. An example of a form that produces side
97 effects is @code{(setq foo 1)}.
99 The details of what evaluation means for each kind of form are
100 described below (@pxref{Forms}).
103 @section Kinds of Forms
105 A Lisp object that is intended to be evaluated is called a @dfn{form}.
106 How Emacs evaluates a form depends on its data type. Emacs has three
107 different kinds of form that are evaluated differently: symbols, lists,
108 and ``all other types''. This section describes all three kinds, one by
109 one, starting with the ``all other types'' which are self-evaluating
113 * Self-Evaluating Forms:: Forms that evaluate to themselves.
114 * Symbol Forms:: Symbols evaluate as variables.
115 * Classifying Lists:: How to distinguish various sorts of list forms.
116 * Function Indirection:: When a symbol appears as the car of a list,
117 we find the real function via the symbol.
118 * Function Forms:: Forms that call functions.
119 * Macro Forms:: Forms that call macros.
120 * Special Forms:: ``Special forms'' are idiosyncratic primitives,
121 most of them extremely important.
122 * Autoloading:: Functions set up to load files
123 containing their real definitions.
126 @node Self-Evaluating Forms
127 @subsection Self-Evaluating Forms
128 @cindex vector evaluation
129 @cindex literal evaluation
130 @cindex self-evaluating form
132 A @dfn{self-evaluating form} is any form that is not a list or symbol.
133 Self-evaluating forms evaluate to themselves: the result of evaluation
134 is the same object that was evaluated. Thus, the number 25 evaluates to
135 25, and the string @code{"foo"} evaluates to the string @code{"foo"}.
136 Likewise, evaluation of a vector does not cause evaluation of the
137 elements of the vector---it returns the same vector with its contents
142 '123 ; @r{An object, shown without evaluation.}
146 123 ; @r{Evaluated as usual---result is the same.}
150 (eval '123) ; @r{Evaluated ``by hand''---result is the same.}
154 (eval (eval '123)) ; @r{Evaluating twice changes nothing.}
159 It is common to write numbers, characters, strings, and even vectors
160 in Lisp code, taking advantage of the fact that they self-evaluate.
161 However, it is quite unusual to do this for types that lack a read
162 syntax, because there's no way to write them textually. It is possible
163 to construct Lisp expressions containing these types by means of a Lisp
164 program. Here is an example:
168 ;; @r{Build an expression containing a buffer object.}
169 (setq print-exp (list 'print (current-buffer)))
170 @result{} (print #<buffer eval.texi>)
175 @print{} #<buffer eval.texi>
176 @result{} #<buffer eval.texi>
181 @subsection Symbol Forms
182 @cindex symbol evaluation
184 When a symbol is evaluated, it is treated as a variable. The result
185 is the variable's value, if it has one. If it has none (if its value
186 cell is void), an error is signaled. For more information on the use of
187 variables, see @ref{Variables}.
189 In the following example, we set the value of a symbol with
190 @code{setq}. Then we evaluate the symbol, and get back the value that
208 The symbols @code{nil} and @code{t} are treated specially, so that the
209 value of @code{nil} is always @code{nil}, and the value of @code{t} is
210 always @code{t}; you cannot set or bind them to any other values. Thus,
211 these two symbols act like self-evaluating forms, even though
212 @code{eval} treats them like any other symbol. A symbol whose name
213 starts with @samp{:} also self-evaluates in the same way.
215 @node Classifying Lists
216 @subsection Classification of List Forms
217 @cindex list form evaluation
219 A form that is a nonempty list is either a function call, a macro
220 call, or a special form, according to its first element. These three
221 kinds of forms are evaluated in different ways, described below. The
222 remaining list elements constitute the @dfn{arguments} for the function,
223 macro, or special form.
225 The first step in evaluating a nonempty list is to examine its first
226 element. This element alone determines what kind of form the list is
227 and how the rest of the list is to be processed. The first element is
228 @emph{not} evaluated, as it would be in some Lisp dialects such as
231 @node Function Indirection
232 @subsection Symbol Function Indirection
233 @cindex symbol function indirection
235 @cindex void function
237 If the first element of the list is a symbol then evaluation examines
238 the symbol's function cell, and uses its contents instead of the
239 original symbol. If the contents are another symbol, this process,
240 called @dfn{symbol function indirection}, is repeated until it obtains a
241 non-symbol. @xref{Function Names}, for more information about using a
242 symbol as a name for a function stored in the function cell of the
245 One possible consequence of this process is an infinite loop, in the
246 event that a symbol's function cell refers to the same symbol. Or a
247 symbol may have a void function cell, in which case the subroutine
248 @code{symbol-function} signals a @code{void-function} error. But if
249 neither of these things happens, we eventually obtain a non-symbol,
250 which ought to be a function or other suitable object.
252 @kindex invalid-function
253 @cindex invalid function
254 More precisely, we should now have a Lisp function (a lambda
255 expression), a byte-code function, a primitive function, a Lisp macro, a
256 special form, or an autoload object. Each of these types is a case
257 described in one of the following sections. If the object is not one of
258 these types, the error @code{invalid-function} is signaled.
260 The following example illustrates the symbol indirection process. We
261 use @code{fset} to set the function cell of a symbol and
262 @code{symbol-function} to get the function cell contents
263 (@pxref{Function Cells}). Specifically, we store the symbol @code{car}
264 into the function cell of @code{first}, and the symbol @code{first} into
265 the function cell of @code{erste}.
269 ;; @r{Build this function cell linkage:}
270 ;; ------------- ----- ------- -------
271 ;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
272 ;; ------------- ----- ------- -------
278 (symbol-function 'car)
279 @result{} #<subr car>
290 (erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.}
295 By contrast, the following example calls a function without any symbol
296 function indirection, because the first element is an anonymous Lisp
297 function, not a symbol.
301 ((lambda (arg) (erste arg))
308 Executing the function itself evaluates its body; this does involve
309 symbol function indirection when calling @code{erste}.
311 The built-in function @code{indirect-function} provides an easy way to
312 perform symbol function indirection explicitly.
315 @defun indirect-function function
316 This function returns the meaning of @var{function} as a function. If
317 @var{function} is a symbol, then it finds @var{function}'s function
318 definition and starts over with that value. If @var{function} is not a
319 symbol, then it returns @var{function} itself.
321 Here is how you could define @code{indirect-function} in Lisp:
324 (defun indirect-function (function)
325 (if (symbolp function)
326 (indirect-function (symbol-function function))
332 @subsection Evaluation of Function Forms
333 @cindex function form evaluation
334 @cindex function call
336 If the first element of a list being evaluated is a Lisp function
337 object, byte-code object or primitive function object, then that list is
338 a @dfn{function call}. For example, here is a call to the function
345 The first step in evaluating a function call is to evaluate the
346 remaining elements of the list from left to right. The results are the
347 actual argument values, one value for each list element. The next step
348 is to call the function with this list of arguments, effectively using
349 the function @code{apply} (@pxref{Calling Functions}). If the function
350 is written in Lisp, the arguments are used to bind the argument
351 variables of the function (@pxref{Lambda Expressions}); then the forms
352 in the function body are evaluated in order, and the value of the last
353 body form becomes the value of the function call.
356 @subsection Lisp Macro Evaluation
357 @cindex macro call evaluation
359 If the first element of a list being evaluated is a macro object, then
360 the list is a @dfn{macro call}. When a macro call is evaluated, the
361 elements of the rest of the list are @emph{not} initially evaluated.
362 Instead, these elements themselves are used as the arguments of the
363 macro. The macro definition computes a replacement form, called the
364 @dfn{expansion} of the macro, to be evaluated in place of the original
365 form. The expansion may be any sort of form: a self-evaluating
366 constant, a symbol, or a list. If the expansion is itself a macro call,
367 this process of expansion repeats until some other sort of form results.
369 Ordinary evaluation of a macro call finishes by evaluating the
370 expansion. However, the macro expansion is not necessarily evaluated
371 right away, or at all, because other programs also expand macro calls,
372 and they may or may not evaluate the expansions.
374 Normally, the argument expressions are not evaluated as part of
375 computing the macro expansion, but instead appear as part of the
376 expansion, so they are computed when the expansion is evaluated.
378 For example, given a macro defined as follows:
383 (list 'car (list 'cdr x)))
388 an expression such as @code{(cadr (assq 'handler list))} is a macro
389 call, and its expansion is:
392 (car (cdr (assq 'handler list)))
396 Note that the argument @code{(assq 'handler list)} appears in the
399 @xref{Macros}, for a complete description of Emacs Lisp macros.
402 @subsection Special Forms
403 @cindex special form evaluation
405 A @dfn{special form} is a primitive function specially marked so that
406 its arguments are not all evaluated. Most special forms define control
407 structures or perform variable bindings---things which functions cannot
410 Each special form has its own rules for which arguments are evaluated
411 and which are used without evaluation. Whether a particular argument is
412 evaluated may depend on the results of evaluating other arguments.
414 Here is a list, in alphabetical order, of all of the special forms in
415 Emacs Lisp with a reference to where each is described.
419 @pxref{Combining Conditions}
422 @pxref{Catch and Throw}
428 @pxref{Handling Errors}
431 @pxref{Defining Variables}
434 @pxref{Defining Macros}
437 @pxref{Defining Functions}
440 @pxref{Defining Variables}
443 @pxref{Anonymous Functions}
449 @pxref{Interactive Call}
453 @pxref{Local Variables}
456 @pxref{Combining Conditions}
469 @item save-restriction
472 @item save-window-excursion
473 @pxref{Window Configurations}
476 @pxref{Setting Variables}
479 @pxref{Creating Buffer-Local}
482 @pxref{Mouse Tracking}
485 @pxref{Nonlocal Exits}
490 @item with-output-to-temp-buffer
491 @pxref{Temporary Displays}
494 @cindex CL note---special forms compared
496 @b{Common Lisp note:} Here are some comparisons of special forms in
497 GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and
498 @code{catch} are special forms in both Emacs Lisp and Common Lisp.
499 @code{defun} is a special form in Emacs Lisp, but a macro in Common
500 Lisp. @code{save-excursion} is a special form in Emacs Lisp, but
501 doesn't exist in Common Lisp. @code{throw} is a special form in
502 Common Lisp (because it must be able to throw multiple values), but it
503 is a function in Emacs Lisp (which doesn't have multiple
508 @subsection Autoloading
510 The @dfn{autoload} feature allows you to call a function or macro
511 whose function definition has not yet been loaded into Emacs. It
512 specifies which file contains the definition. When an autoload object
513 appears as a symbol's function definition, calling that symbol as a
514 function automatically loads the specified file; then it calls the real
515 definition loaded from that file. @xref{Autoload}.
521 The special form @code{quote} returns its single argument, as written,
522 without evaluating it. This provides a way to include constant symbols
523 and lists, which are not self-evaluating objects, in a program. (It is
524 not necessary to quote self-evaluating objects such as numbers, strings,
527 @defspec quote object
528 This special form returns @var{object}, without evaluating it.
531 @cindex @samp{'} for quoting
532 @cindex quoting using apostrophe
533 @cindex apostrophe for quoting
534 Because @code{quote} is used so often in programs, Lisp provides a
535 convenient read syntax for it. An apostrophe character (@samp{'})
536 followed by a Lisp object (in read syntax) expands to a list whose first
537 element is @code{quote}, and whose second element is the object. Thus,
538 the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
540 Here are some examples of expressions that use @code{quote}:
557 @result{} (quote foo)
561 @result{} (quote foo)
565 @result{} [(quote foo)]
569 Other quoting constructs include @code{function} (@pxref{Anonymous
570 Functions}), which causes an anonymous lambda expression written in Lisp
571 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
572 only part of a list, while computing and substituting other parts.
577 Most often, forms are evaluated automatically, by virtue of their
578 occurrence in a program being run. On rare occasions, you may need to
579 write code that evaluates a form that is computed at run time, such as
580 after reading a form from text being edited or getting one from a
581 property list. On these occasions, use the @code{eval} function.
583 The functions and variables described in this section evaluate forms,
584 specify limits to the evaluation process, or record recently returned
585 values. Loading a file also does evaluation (@pxref{Loading}).
587 @strong{Note:} it is generally cleaner and more flexible to store a
588 function in a data structure, and call it with @code{funcall} or
589 @code{apply}, than to store an expression in the data structure and
590 evaluate it. Using functions provides the ability to pass information
591 to them as arguments.
594 This is the basic function evaluating an expression. It evaluates
595 @var{form} in the current environment and returns the result. How the
596 evaluation proceeds depends on the type of the object (@pxref{Forms}).
598 Since @code{eval} is a function, the argument expression that appears
599 in a call to @code{eval} is evaluated twice: once as preparation before
600 @code{eval} is called, and again by the @code{eval} function itself.
611 ;; @r{Here @code{eval} receives argument @code{foo}}
614 ;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}
620 The number of currently active calls to @code{eval} is limited to
621 @code{max-lisp-eval-depth} (see below).
624 @deffn Command eval-region start end &optional stream
625 This function evaluates the forms in the current buffer in the region
626 defined by the positions @var{start} and @var{end}. It reads forms from
627 the region and calls @code{eval} on them until the end of the region is
628 reached, or until an error is signaled and not handled.
630 If @var{stream} is supplied, @code{standard-output} is bound to it
631 during the evaluation.
633 You can use the variable @code{load-read-function} to specify a function
634 for @code{eval-region} to use instead of @code{read} for reading
635 expressions. @xref{How Programs Do Loading}.
637 @code{eval-region} always returns @code{nil}.
640 @cindex evaluation of buffer contents
641 @deffn Command eval-current-buffer &optional stream
642 This is like @code{eval-region} except that it operates on the whole
646 @defvar max-lisp-eval-depth
647 This variable defines the maximum depth allowed in calls to @code{eval},
648 @code{apply}, and @code{funcall} before an error is signaled (with error
649 message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This counts
650 internal uses of those functions, such as for calling the functions
651 mentioned in Lisp expressions, and recursive evaluation of function call
652 arguments and function body forms.
654 This limit, with the associated error when it is exceeded, is one way
655 that Lisp avoids infinite recursion on an ill-defined function.
656 @cindex Lisp nesting error
658 The default value of this variable is 200. If you set it to a value
659 less than 100, Lisp will reset it to 100 if the given value is reached.
661 @code{max-specpdl-size} provides another limit on nesting.
662 @xref{Local Variables}.
666 The value of this variable is a list of the values returned by all the
667 expressions that were read, evaluated, and printed from buffers
668 (including the minibuffer) by the standard Emacs commands which do this.
669 The elements are ordered most recent first.
677 (list 'A (1+ 2) auto-save-default)
682 @result{} ((A 3 t) 1 @dots{})
686 This variable is useful for referring back to values of forms recently
687 evaluated. It is generally a bad idea to print the value of
688 @code{values} itself, since this may be very long. Instead, examine
689 particular elements, like this:
693 ;; @r{Refer to the most recent evaluation result.}
698 ;; @r{That put a new element on,}
699 ;; @r{so all elements move back one.}
704 ;; @r{This gets the element that was next-to-most-recent}
705 ;; @r{before this example.}