2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1994, 1998, 2001-2012 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @node Evaluation, Control Structures, Symbols, Top
10 @cindex value of expression
12 The @dfn{evaluation} of expressions in Emacs Lisp is performed by the
13 @dfn{Lisp interpreter}---a program that receives a Lisp object as input
14 and computes its @dfn{value as an expression}. How it does this depends
15 on the data type of the object, according to rules described in this
16 chapter. The interpreter runs automatically to evaluate portions of
17 your program, but can also be called explicitly via the Lisp primitive
22 * Intro Eval:: Evaluation in the scheme of things.
23 * Forms:: How various sorts of objects are evaluated.
24 * Quoting:: Avoiding evaluation (to put constants in the program).
25 * Backquote:: Easier construction of list structure.
26 * Eval:: How to invoke the Lisp interpreter explicitly.
30 @section Introduction to Evaluation
32 The Lisp interpreter, or evaluator, is the part of Emacs that
33 computes the value of an expression that is given to it. When a
34 function written in Lisp is called, the evaluator computes the value
35 of the function by evaluating the expressions in the function body.
36 Thus, running any Lisp program really means running the Lisp
43 A Lisp object that is intended for evaluation is called a @dfn{form}
44 or @dfn{expression}@footnote{It is sometimes also referred to as an
45 @dfn{S-expression} or @dfn{sexp}, but we generally do not use this
46 terminology in this manual.}. The fact that forms are data objects
47 and not merely text is one of the fundamental differences between
48 Lisp-like languages and typical programming languages. Any object can
49 be evaluated, but in practice only numbers, symbols, lists and strings
50 are evaluated very often.
52 In subsequent sections, we will describe the details of what
53 evaluation means for each kind of form.
55 It is very common to read a Lisp form and then evaluate the form,
56 but reading and evaluation are separate activities, and either can be
57 performed alone. Reading per se does not evaluate anything; it
58 converts the printed representation of a Lisp object to the object
59 itself. It is up to the caller of @code{read} to specify whether this
60 object is a form to be evaluated, or serves some entirely different
61 purpose. @xref{Input Functions}.
63 @cindex recursive evaluation
64 Evaluation is a recursive process, and evaluating a form often
65 involves evaluating parts within that form. For instance, when you
66 evaluate a @dfn{function call} form such as @code{(car x)}, Emacs
67 first evaluates the argument (the subform @code{x}). After evaluating
68 the argument, Emacs @dfn{executes} the function (@code{car}), and if
69 the function is written in Lisp, execution works by evaluating the
70 @dfn{body} of the function (in this example, however, @code{car} is
71 not a Lisp function; it is a primitive function implemented in C).
72 @xref{Functions}, for more information about functions and function
76 Evaluation takes place in a context called the @dfn{environment},
77 which consists of the current values and bindings of all Lisp
78 variables (@pxref{Variables}).@footnote{This definition of
79 ``environment'' is specifically not intended to include all the data
80 that can affect the result of a program.} Whenever a form refers to a
81 variable without creating a new binding for it, the variable evaluates
82 to the value given by the current environment. Evaluating a form may
83 also temporarily alter the environment by binding variables
84 (@pxref{Local Variables}).
87 Evaluating a form may also make changes that persist; these changes
88 are called @dfn{side effects}. An example of a form that produces a
89 side effect is @code{(setq foo 1)}.
91 Do not confuse evaluation with command key interpretation. The
92 editor command loop translates keyboard input into a command (an
93 interactively callable function) using the active keymaps, and then
94 uses @code{call-interactively} to execute that command. Executing the
95 command usually involves evaluation, if the command is written in
96 Lisp; however, this step is not considered a part of command key
97 interpretation. @xref{Command Loop}.
100 @section Kinds of Forms
102 A Lisp object that is intended to be evaluated is called a
103 @dfn{form} (or an @dfn{expression}). How Emacs evaluates a form
104 depends on its data type. Emacs has three different kinds of form
105 that are evaluated differently: symbols, lists, and ``all other
106 types.'' This section describes all three kinds, one by one, starting
107 with the ``all other types'' which are self-evaluating forms.
110 * Self-Evaluating Forms:: Forms that evaluate to themselves.
111 * Symbol Forms:: Symbols evaluate as variables.
112 * Classifying Lists:: How to distinguish various sorts of list forms.
113 * Function Indirection:: When a symbol appears as the car of a list,
114 we find the real function via the symbol.
115 * Function Forms:: Forms that call functions.
116 * Macro Forms:: Forms that call macros.
117 * Special Forms:: "Special forms" are idiosyncratic primitives,
118 most of them extremely important.
119 * Autoloading:: Functions set up to load files
120 containing their real definitions.
123 @node Self-Evaluating Forms
124 @subsection Self-Evaluating Forms
125 @cindex vector evaluation
126 @cindex literal evaluation
127 @cindex self-evaluating form
129 A @dfn{self-evaluating form} is any form that is not a list or
130 symbol. Self-evaluating forms evaluate to themselves: the result of
131 evaluation is the same object that was evaluated. Thus, the number 25
132 evaluates to 25, and the string @code{"foo"} evaluates to the string
133 @code{"foo"}. Likewise, evaluating a vector does not cause evaluation
134 of the elements of the vector---it returns the same vector with its
139 '123 ; @r{A number, shown without evaluation.}
143 123 ; @r{Evaluated as usual---result is the same.}
147 (eval '123) ; @r{Evaluated ``by hand''---result is the same.}
151 (eval (eval '123)) ; @r{Evaluating twice changes nothing.}
156 It is common to write numbers, characters, strings, and even vectors
157 in Lisp code, taking advantage of the fact that they self-evaluate.
158 However, it is quite unusual to do this for types that lack a read
159 syntax, because there's no way to write them textually. It is possible
160 to construct Lisp expressions containing these types by means of a Lisp
161 program. Here is an example:
165 ;; @r{Build an expression containing a buffer object.}
166 (setq print-exp (list 'print (current-buffer)))
167 @result{} (print #<buffer eval.texi>)
172 @print{} #<buffer eval.texi>
173 @result{} #<buffer eval.texi>
178 @subsection Symbol Forms
179 @cindex symbol evaluation
181 When a symbol is evaluated, it is treated as a variable. The result
182 is the variable's value, if it has one. If the symbol has no value as
183 a variable, the Lisp interpreter signals an error. For more
184 information on the use of variables, see @ref{Variables}.
186 In the following example, we set the value of a symbol with
187 @code{setq}. Then we evaluate the symbol, and get back the value that
205 The symbols @code{nil} and @code{t} are treated specially, so that the
206 value of @code{nil} is always @code{nil}, and the value of @code{t} is
207 always @code{t}; you cannot set or bind them to any other values. Thus,
208 these two symbols act like self-evaluating forms, even though
209 @code{eval} treats them like any other symbol. A symbol whose name
210 starts with @samp{:} also self-evaluates in the same way; likewise,
211 its value ordinarily cannot be changed. @xref{Constant Variables}.
213 @node Classifying Lists
214 @subsection Classification of List Forms
215 @cindex list form evaluation
217 A form that is a nonempty list is either a function call, a macro
218 call, or a special form, according to its first element. These three
219 kinds of forms are evaluated in different ways, described below. The
220 remaining list elements constitute the @dfn{arguments} for the function,
221 macro, or special form.
223 The first step in evaluating a nonempty list is to examine its first
224 element. This element alone determines what kind of form the list is
225 and how the rest of the list is to be processed. The first element is
226 @emph{not} evaluated, as it would be in some Lisp dialects such as
229 @node Function Indirection
230 @subsection Symbol Function Indirection
231 @cindex symbol function indirection
232 @cindex indirection for functions
233 @cindex void function
235 If the first element of the list is a symbol then evaluation
236 examines the symbol's function cell, and uses its contents instead of
237 the original symbol. If the contents are another symbol, this
238 process, called @dfn{symbol function indirection}, is repeated until
239 it obtains a non-symbol. @xref{Function Names}, for more information
240 about symbol function indirection.
242 One possible consequence of this process is an infinite loop, in the
243 event that a symbol's function cell refers to the same symbol. Or a
244 symbol may have a void function cell, in which case the subroutine
245 @code{symbol-function} signals a @code{void-function} error. But if
246 neither of these things happens, we eventually obtain a non-symbol,
247 which ought to be a function or other suitable object.
249 @kindex invalid-function
250 More precisely, we should now have a Lisp function (a lambda
251 expression), a byte-code function, a primitive function, a Lisp macro,
252 a special form, or an autoload object. Each of these types is a case
253 described in one of the following sections. If the object is not one
254 of these types, Emacs signals an @code{invalid-function} error.
256 The following example illustrates the symbol indirection process. We
257 use @code{fset} to set the function cell of a symbol and
258 @code{symbol-function} to get the function cell contents
259 (@pxref{Function Cells}). Specifically, we store the symbol @code{car}
260 into the function cell of @code{first}, and the symbol @code{first} into
261 the function cell of @code{erste}.
265 ;; @r{Build this function cell linkage:}
266 ;; ------------- ----- ------- -------
267 ;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
268 ;; ------------- ----- ------- -------
274 (symbol-function 'car)
275 @result{} #<subr car>
286 (erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.}
291 By contrast, the following example calls a function without any symbol
292 function indirection, because the first element is an anonymous Lisp
293 function, not a symbol.
297 ((lambda (arg) (erste arg))
304 Executing the function itself evaluates its body; this does involve
305 symbol function indirection when calling @code{erste}.
307 The built-in function @code{indirect-function} provides an easy way to
308 perform symbol function indirection explicitly.
311 @defun indirect-function function &optional noerror
312 @anchor{Definition of indirect-function}
313 This function returns the meaning of @var{function} as a function. If
314 @var{function} is a symbol, then it finds @var{function}'s function
315 definition and starts over with that value. If @var{function} is not a
316 symbol, then it returns @var{function} itself.
318 This function signals a @code{void-function} error if the final symbol
319 is unbound and optional argument @var{noerror} is @code{nil} or
320 omitted. Otherwise, if @var{noerror} is non-@code{nil}, it returns
321 @code{nil} if the final symbol is unbound.
323 It signals a @code{cyclic-function-indirection} error if there is a
324 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 forms
409 @cindex evaluation of special forms
411 A @dfn{special form} is a primitive function specially marked so that
412 its arguments are not all evaluated. Most special forms define control
413 structures or perform variable bindings---things which functions cannot
416 Each special form has its own rules for which arguments are evaluated
417 and which are used without evaluation. Whether a particular argument is
418 evaluated may depend on the results of evaluating other arguments.
420 Here is a list, in alphabetical order, of all of the special forms in
421 Emacs Lisp with a reference to where each is described.
425 @pxref{Combining Conditions}
428 @pxref{Catch and Throw}
434 @pxref{Handling Errors}
437 @pxref{Defining Variables}
440 @pxref{Defining Macros}
443 @pxref{Defining Functions}
446 @pxref{Defining Variables}
449 @pxref{Anonymous Functions}
455 @pxref{Interactive Call}
459 @pxref{Local Variables}
462 @pxref{Combining Conditions}
472 @item save-current-buffer
473 @pxref{Current Buffer}
478 @item save-restriction
481 @item save-window-excursion
482 @pxref{Window Configurations}
485 @pxref{Setting Variables}
488 @pxref{Creating Buffer-Local}
491 @pxref{Mouse Tracking}
494 @pxref{Nonlocal Exits}
499 @item with-output-to-temp-buffer
500 @pxref{Temporary Displays}
503 @cindex CL note---special forms compared
505 @b{Common Lisp note:} Here are some comparisons of special forms in
506 GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and
507 @code{catch} are special forms in both Emacs Lisp and Common Lisp.
508 @code{defun} is a special form in Emacs Lisp, but a macro in Common
509 Lisp. @code{save-excursion} is a special form in Emacs Lisp, but
510 doesn't exist in Common Lisp. @code{throw} is a special form in
511 Common Lisp (because it must be able to throw multiple values), but it
512 is a function in Emacs Lisp (which doesn't have multiple
517 @subsection Autoloading
519 The @dfn{autoload} feature allows you to call a function or macro
520 whose function definition has not yet been loaded into Emacs. It
521 specifies which file contains the definition. When an autoload object
522 appears as a symbol's function definition, calling that symbol as a
523 function automatically loads the specified file; then it calls the
524 real definition loaded from that file. The way to arrange for an
525 autoload object to appear as a symbol's function definition is
526 described in @ref{Autoload}.
531 The special form @code{quote} returns its single argument, as written,
532 without evaluating it. This provides a way to include constant symbols
533 and lists, which are not self-evaluating objects, in a program. (It is
534 not necessary to quote self-evaluating objects such as numbers, strings,
537 @defspec quote object
538 This special form returns @var{object}, without evaluating it.
541 @cindex @samp{'} for quoting
542 @cindex quoting using apostrophe
543 @cindex apostrophe for quoting
544 Because @code{quote} is used so often in programs, Lisp provides a
545 convenient read syntax for it. An apostrophe character (@samp{'})
546 followed by a Lisp object (in read syntax) expands to a list whose first
547 element is @code{quote}, and whose second element is the object. Thus,
548 the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
550 Here are some examples of expressions that use @code{quote}:
567 @result{} (quote foo)
571 @result{} (quote foo)
575 @result{} [(quote foo)]
579 Other quoting constructs include @code{function} (@pxref{Anonymous
580 Functions}), which causes an anonymous lambda expression written in Lisp
581 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
582 only part of a list, while computing and substituting other parts.
586 @cindex backquote (list substitution)
587 @cindex ` (list substitution)
590 @dfn{Backquote constructs} allow you to quote a list, but
591 selectively evaluate elements of that list. In the simplest case, it
592 is identical to the special form @code{quote}
596 (described in the previous section; @pxref{Quoting}).
598 For example, these two forms yield identical results:
602 `(a list of (+ 2 3) elements)
603 @result{} (a list of (+ 2 3) elements)
606 '(a list of (+ 2 3) elements)
607 @result{} (a list of (+ 2 3) elements)
611 @findex , @r{(with backquote)}
612 The special marker @samp{,} inside of the argument to backquote
613 indicates a value that isn't constant. The Emacs Lisp evaluator
614 evaluates the argument of @samp{,}, and puts the value in the list
619 `(a list of ,(+ 2 3) elements)
620 @result{} (a list of 5 elements)
625 Substitution with @samp{,} is allowed at deeper levels of the list
626 structure also. For example:
631 @result{} (1 2 (3 9))
635 @findex ,@@ @r{(with backquote)}
636 @cindex splicing (with backquote)
637 You can also @dfn{splice} an evaluated value into the resulting list,
638 using the special marker @samp{,@@}. The elements of the spliced list
639 become elements at the same level as the other elements of the resulting
640 list. The equivalent code without using @samp{`} is often unreadable.
641 Here are some examples:
645 (setq some-list '(2 3))
649 (cons 1 (append some-list '(4) some-list))
650 @result{} (1 2 3 4 2 3)
653 `(1 ,@@some-list 4 ,@@some-list)
654 @result{} (1 2 3 4 2 3)
658 (setq list '(hack foo bar))
659 @result{} (hack foo bar)
664 (cons 'words (append (cdr list) '(as elements)))))
665 @result{} (use the words foo bar as elements)
668 `(use the words ,@@(cdr list) as elements)
669 @result{} (use the words foo bar as elements)
677 Most often, forms are evaluated automatically, by virtue of their
678 occurrence in a program being run. On rare occasions, you may need to
679 write code that evaluates a form that is computed at run time, such as
680 after reading a form from text being edited or getting one from a
681 property list. On these occasions, use the @code{eval} function.
682 Often @code{eval} is not needed and something else should be used instead.
683 For example, to get the value of a variable, while @code{eval} works,
684 @code{symbol-value} is preferable; or rather than store expressions
685 in a property list that then need to go through @code{eval}, it is better to
686 store functions instead that are then passed to @code{funcall}.
688 The functions and variables described in this section evaluate forms,
689 specify limits to the evaluation process, or record recently returned
690 values. Loading a file also does evaluation (@pxref{Loading}).
692 It is generally cleaner and more flexible to store a function in a
693 data structure, and call it with @code{funcall} or @code{apply}, than
694 to store an expression in the data structure and evaluate it. Using
695 functions provides the ability to pass information to them as
698 @defun eval form &optional lexical
699 This is the basic function for evaluating an expression. It evaluates
700 @var{form} in the current environment and returns the result. How the
701 evaluation proceeds depends on the type of the object (@pxref{Forms}).
703 The argument @var{lexical}, if non-@code{nil}, means to evaluate
704 @var{form} using lexical scoping rules for variables, instead of the
705 default dynamic scoping rules. @xref{Lexical Binding}.
707 Since @code{eval} is a function, the argument expression that appears
708 in a call to @code{eval} is evaluated twice: once as preparation before
709 @code{eval} is called, and again by the @code{eval} function itself.
720 ;; @r{Here @code{eval} receives argument @code{foo}}
723 ;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}
729 The number of currently active calls to @code{eval} is limited to
730 @code{max-lisp-eval-depth} (see below).
733 @deffn Command eval-region start end &optional stream read-function
734 @anchor{Definition of eval-region}
735 This function evaluates the forms in the current buffer in the region
736 defined by the positions @var{start} and @var{end}. It reads forms from
737 the region and calls @code{eval} on them until the end of the region is
738 reached, or until an error is signaled and not handled.
740 By default, @code{eval-region} does not produce any output. However,
741 if @var{stream} is non-@code{nil}, any output produced by output
742 functions (@pxref{Output Functions}), as well as the values that
743 result from evaluating the expressions in the region are printed using
744 @var{stream}. @xref{Output Streams}.
746 If @var{read-function} is non-@code{nil}, it should be a function,
747 which is used instead of @code{read} to read expressions one by one.
748 This function is called with one argument, the stream for reading
749 input. You can also use the variable @code{load-read-function}
750 (@pxref{Definition of load-read-function,, How Programs Do Loading})
751 to specify this function, but it is more robust to use the
752 @var{read-function} argument.
754 @code{eval-region} does not move point. It always returns @code{nil}.
757 @cindex evaluation of buffer contents
758 @deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
759 This is similar to @code{eval-region}, but the arguments provide
760 different optional features. @code{eval-buffer} operates on the
761 entire accessible portion of buffer @var{buffer-or-name}.
762 @var{buffer-or-name} can be a buffer, a buffer name (a string), or
763 @code{nil} (or omitted), which means to use the current buffer.
764 @var{stream} is used as in @code{eval-region}, unless @var{stream} is
765 @code{nil} and @var{print} non-@code{nil}. In that case, values that
766 result from evaluating the expressions are still discarded, but the
767 output of the output functions is printed in the echo area.
768 @var{filename} is the file name to use for @code{load-history}
769 (@pxref{Unloading}), and defaults to @code{buffer-file-name}
770 (@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil},
771 @code{read} converts strings to unibyte whenever possible.
773 @findex eval-current-buffer
774 @code{eval-current-buffer} is an alias for this command.
777 @defopt max-lisp-eval-depth
778 @anchor{Definition of max-lisp-eval-depth}
779 This variable defines the maximum depth allowed in calls to @code{eval},
780 @code{apply}, and @code{funcall} before an error is signaled (with error
781 message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).
783 This limit, with the associated error when it is exceeded, is one way
784 Emacs Lisp avoids infinite recursion on an ill-defined function. If
785 you increase the value of @code{max-lisp-eval-depth} too much, such
786 code can cause stack overflow instead.
787 @cindex Lisp nesting error
789 The depth limit counts internal uses of @code{eval}, @code{apply}, and
790 @code{funcall}, such as for calling the functions mentioned in Lisp
791 expressions, and recursive evaluation of function call arguments and
792 function body forms, as well as explicit calls in Lisp code.
794 The default value of this variable is 400. If you set it to a value
795 less than 100, Lisp will reset it to 100 if the given value is
796 reached. Entry to the Lisp debugger increases the value, if there is
797 little room left, to make sure the debugger itself has room to
800 @code{max-specpdl-size} provides another limit on nesting.
801 @xref{Definition of max-specpdl-size,, Local Variables}.
805 The value of this variable is a list of the values returned by all the
806 expressions that were read, evaluated, and printed from buffers
807 (including the minibuffer) by the standard Emacs commands which do
808 this. (Note that this does @emph{not} include evaluation in
809 @file{*ielm*} buffers, nor evaluation using @kbd{C-j} in
810 @code{lisp-interaction-mode}.) The elements are ordered most recent
819 (list 'A (1+ 2) auto-save-default)
824 @result{} ((A 3 t) 1 @dots{})
828 This variable is useful for referring back to values of forms recently
829 evaluated. It is generally a bad idea to print the value of
830 @code{values} itself, since this may be very long. Instead, examine
831 particular elements, like this:
835 ;; @r{Refer to the most recent evaluation result.}
840 ;; @r{That put a new element on,}
841 ;; @r{so all elements move back one.}
846 ;; @r{This gets the element that was next-to-most-recent}
847 ;; @r{before this example.}