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{A number, 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; likewise,
214 its value ordinarily cannot be changed. @xref{Constant Variables}.
216 @node Classifying Lists
217 @subsection Classification of List Forms
218 @cindex list form evaluation
220 A form that is a nonempty list is either a function call, a macro
221 call, or a special form, according to its first element. These three
222 kinds of forms are evaluated in different ways, described below. The
223 remaining list elements constitute the @dfn{arguments} for the function,
224 macro, or special form.
226 The first step in evaluating a nonempty list is to examine its first
227 element. This element alone determines what kind of form the list is
228 and how the rest of the list is to be processed. The first element is
229 @emph{not} evaluated, as it would be in some Lisp dialects such as
232 @node Function Indirection
233 @subsection Symbol Function Indirection
234 @cindex symbol function indirection
236 @cindex void function
238 If the first element of the list is a symbol then evaluation examines
239 the symbol's function cell, and uses its contents instead of the
240 original symbol. If the contents are another symbol, this process,
241 called @dfn{symbol function indirection}, is repeated until it obtains a
242 non-symbol. @xref{Function Names}, for more information about using a
243 symbol as a name for a function stored in the function cell of the
246 One possible consequence of this process is an infinite loop, in the
247 event that a symbol's function cell refers to the same symbol. Or a
248 symbol may have a void function cell, in which case the subroutine
249 @code{symbol-function} signals a @code{void-function} error. But if
250 neither of these things happens, we eventually obtain a non-symbol,
251 which ought to be a function or other suitable object.
253 @kindex invalid-function
254 @cindex invalid function
255 More precisely, we should now have a Lisp function (a lambda
256 expression), a byte-code function, a primitive function, a Lisp macro, a
257 special form, or an autoload object. Each of these types is a case
258 described in one of the following sections. If the object is not one of
259 these types, the error @code{invalid-function} is signaled.
261 The following example illustrates the symbol indirection process. We
262 use @code{fset} to set the function cell of a symbol and
263 @code{symbol-function} to get the function cell contents
264 (@pxref{Function Cells}). Specifically, we store the symbol @code{car}
265 into the function cell of @code{first}, and the symbol @code{first} into
266 the function cell of @code{erste}.
270 ;; @r{Build this function cell linkage:}
271 ;; ------------- ----- ------- -------
272 ;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
273 ;; ------------- ----- ------- -------
279 (symbol-function 'car)
280 @result{} #<subr car>
291 (erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.}
296 By contrast, the following example calls a function without any symbol
297 function indirection, because the first element is an anonymous Lisp
298 function, not a symbol.
302 ((lambda (arg) (erste arg))
309 Executing the function itself evaluates its body; this does involve
310 symbol function indirection when calling @code{erste}.
312 The built-in function @code{indirect-function} provides an easy way to
313 perform symbol function indirection explicitly.
316 @defun indirect-function function
317 This function returns the meaning of @var{function} as a function. If
318 @var{function} is a symbol, then it finds @var{function}'s function
319 definition and starts over with that value. If @var{function} is not a
320 symbol, then it returns @var{function} itself.
322 This function signals a @code{void-function} error if the final
323 symbol is unbound and a @code{cyclic-function-indirection} error if
324 there is a loop in the chain of symbols.
326 Here is how you could define @code{indirect-function} in Lisp:
329 (defun indirect-function (function)
330 (if (symbolp function)
331 (indirect-function (symbol-function function))
337 @subsection Evaluation of Function Forms
338 @cindex function form evaluation
339 @cindex function call
341 If the first element of a list being evaluated is a Lisp function
342 object, byte-code object or primitive function object, then that list is
343 a @dfn{function call}. For example, here is a call to the function
350 The first step in evaluating a function call is to evaluate the
351 remaining elements of the list from left to right. The results are the
352 actual argument values, one value for each list element. The next step
353 is to call the function with this list of arguments, effectively using
354 the function @code{apply} (@pxref{Calling Functions}). If the function
355 is written in Lisp, the arguments are used to bind the argument
356 variables of the function (@pxref{Lambda Expressions}); then the forms
357 in the function body are evaluated in order, and the value of the last
358 body form becomes the value of the function call.
361 @subsection Lisp Macro Evaluation
362 @cindex macro call evaluation
364 If the first element of a list being evaluated is a macro object, then
365 the list is a @dfn{macro call}. When a macro call is evaluated, the
366 elements of the rest of the list are @emph{not} initially evaluated.
367 Instead, these elements themselves are used as the arguments of the
368 macro. The macro definition computes a replacement form, called the
369 @dfn{expansion} of the macro, to be evaluated in place of the original
370 form. The expansion may be any sort of form: a self-evaluating
371 constant, a symbol, or a list. If the expansion is itself a macro call,
372 this process of expansion repeats until some other sort of form results.
374 Ordinary evaluation of a macro call finishes by evaluating the
375 expansion. However, the macro expansion is not necessarily evaluated
376 right away, or at all, because other programs also expand macro calls,
377 and they may or may not evaluate the expansions.
379 Normally, the argument expressions are not evaluated as part of
380 computing the macro expansion, but instead appear as part of the
381 expansion, so they are computed when the expansion is evaluated.
383 For example, given a macro defined as follows:
388 (list 'car (list 'cdr x)))
393 an expression such as @code{(cadr (assq 'handler list))} is a macro
394 call, and its expansion is:
397 (car (cdr (assq 'handler list)))
401 Note that the argument @code{(assq 'handler list)} appears in the
404 @xref{Macros}, for a complete description of Emacs Lisp macros.
407 @subsection Special Forms
408 @cindex special form evaluation
410 A @dfn{special form} is a primitive function specially marked so that
411 its arguments are not all evaluated. Most special forms define control
412 structures or perform variable bindings---things which functions cannot
415 Each special form has its own rules for which arguments are evaluated
416 and which are used without evaluation. Whether a particular argument is
417 evaluated may depend on the results of evaluating other arguments.
419 Here is a list, in alphabetical order, of all of the special forms in
420 Emacs Lisp with a reference to where each is described.
424 @pxref{Combining Conditions}
427 @pxref{Catch and Throw}
433 @pxref{Handling Errors}
436 @pxref{Defining Variables}
439 @pxref{Defining Macros}
442 @pxref{Defining Functions}
445 @pxref{Defining Variables}
448 @pxref{Anonymous Functions}
454 @pxref{Interactive Call}
458 @pxref{Local Variables}
461 @pxref{Combining Conditions}
471 @item save-current-buffer
472 @pxref{Current Buffer}
477 @item save-restriction
480 @item save-window-excursion
481 @pxref{Window Configurations}
484 @pxref{Setting Variables}
487 @pxref{Creating Buffer-Local}
490 @pxref{Mouse Tracking}
493 @pxref{Nonlocal Exits}
498 @item with-output-to-temp-buffer
499 @pxref{Temporary Displays}
502 @cindex CL note---special forms compared
504 @b{Common Lisp note:} Here are some comparisons of special forms in
505 GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and
506 @code{catch} are special forms in both Emacs Lisp and Common Lisp.
507 @code{defun} is a special form in Emacs Lisp, but a macro in Common
508 Lisp. @code{save-excursion} is a special form in Emacs Lisp, but
509 doesn't exist in Common Lisp. @code{throw} is a special form in
510 Common Lisp (because it must be able to throw multiple values), but it
511 is a function in Emacs Lisp (which doesn't have multiple
516 @subsection Autoloading
518 The @dfn{autoload} feature allows you to call a function or macro
519 whose function definition has not yet been loaded into Emacs. It
520 specifies which file contains the definition. When an autoload object
521 appears as a symbol's function definition, calling that symbol as a
522 function automatically loads the specified file; then it calls the real
523 definition loaded from that file. @xref{Autoload}.
529 The special form @code{quote} returns its single argument, as written,
530 without evaluating it. This provides a way to include constant symbols
531 and lists, which are not self-evaluating objects, in a program. (It is
532 not necessary to quote self-evaluating objects such as numbers, strings,
535 @defspec quote object
536 This special form returns @var{object}, without evaluating it.
539 @cindex @samp{'} for quoting
540 @cindex quoting using apostrophe
541 @cindex apostrophe for quoting
542 Because @code{quote} is used so often in programs, Lisp provides a
543 convenient read syntax for it. An apostrophe character (@samp{'})
544 followed by a Lisp object (in read syntax) expands to a list whose first
545 element is @code{quote}, and whose second element is the object. Thus,
546 the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
548 Here are some examples of expressions that use @code{quote}:
565 @result{} (quote foo)
569 @result{} (quote foo)
573 @result{} [(quote foo)]
577 Other quoting constructs include @code{function} (@pxref{Anonymous
578 Functions}), which causes an anonymous lambda expression written in Lisp
579 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
580 only part of a list, while computing and substituting other parts.
585 Most often, forms are evaluated automatically, by virtue of their
586 occurrence in a program being run. On rare occasions, you may need to
587 write code that evaluates a form that is computed at run time, such as
588 after reading a form from text being edited or getting one from a
589 property list. On these occasions, use the @code{eval} function.
591 The functions and variables described in this section evaluate forms,
592 specify limits to the evaluation process, or record recently returned
593 values. Loading a file also does evaluation (@pxref{Loading}).
595 It is generally cleaner and more flexible to store a function in a
596 data structure, and call it with @code{funcall} or @code{apply}, than
597 to store an expression in the data structure and evaluate it. Using
598 functions provides the ability to pass information to them as
602 This is the basic function evaluating an expression. It evaluates
603 @var{form} in the current environment and returns the result. How the
604 evaluation proceeds depends on the type of the object (@pxref{Forms}).
606 Since @code{eval} is a function, the argument expression that appears
607 in a call to @code{eval} is evaluated twice: once as preparation before
608 @code{eval} is called, and again by the @code{eval} function itself.
619 ;; @r{Here @code{eval} receives argument @code{foo}}
622 ;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}
628 The number of currently active calls to @code{eval} is limited to
629 @code{max-lisp-eval-depth} (see below).
632 @anchor{Definition of eval-region}
633 @deffn Command eval-region start end &optional stream read-function
634 This function evaluates the forms in the current buffer in the region
635 defined by the positions @var{start} and @var{end}. It reads forms from
636 the region and calls @code{eval} on them until the end of the region is
637 reached, or until an error is signaled and not handled.
639 By default, @code{eval-region} does not produce any output. However,
640 if @var{stream} is non-@code{nil}, any output produced by output
641 functions (@pxref{Output Functions}), as well as the values that
642 result from evaluating the expressions in the region are printed using
643 @var{stream}. @xref{Output Streams}.
645 If @var{read-function} is non-@code{nil}, it should be a function,
646 which is used instead of @code{read} to read expressions one by one.
647 This function is called with one argument, the stream for reading
648 input. You can also use the variable @code{load-read-function}
649 (@pxref{Definition of load-read-function,, How Programs Do Loading})
650 to specify this function, but it is more robust to use the
651 @var{read-function} argument.
653 @code{eval-region} does not move point. It always returns @code{nil}.
656 @cindex evaluation of buffer contents
657 @deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
658 This is similar to @code{eval-region}, but the arguments provide
659 different optional features. @code{eval-buffer} operates on the
660 entire accessible portion of buffer @var{buffer-or-name}.
661 @var{buffer-or-name} can be a buffer, a buffer name (a string), or
662 @code{nil} (or omitted), which means to use the current buffer.
663 @var{stream} is used as in @code{eval-region}, unless @var{stream} is
664 @code{nil} and @var{print} non-@code{nil}. In that case, values that
665 result from evaluating the expressions are still discarded, but the
666 output of the output functions is printed in the echo area.
667 @var{filename} is the file name to use for @code{load-history}
668 (@pxref{Unloading}), and defaults to @code{buffer-file-name}
669 (@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil},
670 @code{read} converts strings to unibyte whenever possible.
672 @findex eval-current-buffer
673 @code{eval-current-buffer} is an alias for this command.
676 @anchor{Definition of max-lisp-eval-depth}
677 @defvar max-lisp-eval-depth
678 This variable defines the maximum depth allowed in calls to @code{eval},
679 @code{apply}, and @code{funcall} before an error is signaled (with error
680 message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This limit,
681 with the associated error when it is exceeded, is one way that Lisp
682 avoids infinite recursion on an ill-defined function.
683 @cindex Lisp nesting error
685 The depth limit counts internal uses of @code{eval}, @code{apply}, and
686 @code{funcall}, such as for calling the functions mentioned in Lisp
687 expressions, and recursive evaluation of function call arguments and
688 function body forms, as well as explicit calls in Lisp code.
690 The default value of this variable is 300. If you set it to a value
691 less than 100, Lisp will reset it to 100 if the given value is reached.
692 Entry to the Lisp debugger increases the value, if there is little room
693 left, to make sure the debugger itself has room to execute.
695 @code{max-specpdl-size} provides another limit on nesting.
696 @xref{Definition of max-specpdl-size,, Local Variables}.
700 The value of this variable is a list of the values returned by all the
701 expressions that were read, evaluated, and printed from buffers
702 (including the minibuffer) by the standard Emacs commands which do
703 this. (Note that this does @emph{not} include evaluation in
704 @samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in
705 @code{lisp-interaction-mode}.) The elements are ordered most recent
714 (list 'A (1+ 2) auto-save-default)
719 @result{} ((A 3 t) 1 @dots{})
723 This variable is useful for referring back to values of forms recently
724 evaluated. It is generally a bad idea to print the value of
725 @code{values} itself, since this may be very long. Instead, examine
726 particular elements, like this:
730 ;; @r{Refer to the most recent evaluation result.}
735 ;; @r{That put a new element on,}
736 ;; @r{so all elements move back one.}
741 ;; @r{This gets the element that was next-to-most-recent}
742 ;; @r{before this example.}
750 arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57