2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1994, 1998, 2001-2013 Free Software Foundation,
5 @c See the file elisp.texi for copying conditions.
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 * Backquote:: Easier construction of list structure.
27 * Eval:: How to invoke the Lisp interpreter explicitly.
31 @section Introduction to Evaluation
33 The Lisp interpreter, or evaluator, is the part of Emacs that
34 computes the value of an expression that is given to it. When a
35 function written in Lisp is called, the evaluator computes the value
36 of the function by evaluating the expressions in the function body.
37 Thus, running any Lisp program really means running the Lisp
45 A Lisp object that is intended for evaluation is called a @dfn{form}
46 or @dfn{expression}@footnote{It is sometimes also referred to as an
47 @dfn{S-expression} or @dfn{sexp}, but we generally do not use this
48 terminology in this manual.}. The fact that forms are data objects
49 and not merely text is one of the fundamental differences between
50 Lisp-like languages and typical programming languages. Any object can
51 be evaluated, but in practice only numbers, symbols, lists and strings
52 are evaluated very often.
54 In subsequent sections, we will describe the details of what
55 evaluation means for each kind of form.
57 It is very common to read a Lisp form and then evaluate the form,
58 but reading and evaluation are separate activities, and either can be
59 performed alone. Reading per se does not evaluate anything; it
60 converts the printed representation of a Lisp object to the object
61 itself. It is up to the caller of @code{read} to specify whether this
62 object is a form to be evaluated, or serves some entirely different
63 purpose. @xref{Input Functions}.
65 @cindex recursive evaluation
66 Evaluation is a recursive process, and evaluating a form often
67 involves evaluating parts within that form. For instance, when you
68 evaluate a @dfn{function call} form such as @code{(car x)}, Emacs
69 first evaluates the argument (the subform @code{x}). After evaluating
70 the argument, Emacs @dfn{executes} the function (@code{car}), and if
71 the function is written in Lisp, execution works by evaluating the
72 @dfn{body} of the function (in this example, however, @code{car} is
73 not a Lisp function; it is a primitive function implemented in C).
74 @xref{Functions}, for more information about functions and function
78 Evaluation takes place in a context called the @dfn{environment},
79 which consists of the current values and bindings of all Lisp
80 variables (@pxref{Variables}).@footnote{This definition of
81 ``environment'' is specifically not intended to include all the data
82 that can affect the result of a program.} Whenever a form refers to a
83 variable without creating a new binding for it, the variable evaluates
84 to the value given by the current environment. Evaluating a form may
85 also temporarily alter the environment by binding variables
86 (@pxref{Local Variables}).
89 Evaluating a form may also make changes that persist; these changes
90 are called @dfn{side effects}. An example of a form that produces a
91 side effect is @code{(setq foo 1)}.
93 Do not confuse evaluation with command key interpretation. The
94 editor command loop translates keyboard input into a command (an
95 interactively callable function) using the active keymaps, and then
96 uses @code{call-interactively} to execute that command. Executing the
97 command usually involves evaluation, if the command is written in
98 Lisp; however, this step is not considered a part of command key
99 interpretation. @xref{Command Loop}.
102 @section Kinds of Forms
104 A Lisp object that is intended to be evaluated is called a
105 @dfn{form} (or an @dfn{expression}). How Emacs evaluates a form
106 depends on its data type. Emacs has three different kinds of form
107 that are evaluated differently: symbols, lists, and ``all other
108 types''. This section describes all three kinds, one by one, starting
109 with the ``all other types'' which are self-evaluating forms.
112 * Self-Evaluating Forms:: Forms that evaluate to themselves.
113 * Symbol Forms:: Symbols evaluate as variables.
114 * Classifying Lists:: How to distinguish various sorts of list forms.
115 * Function Indirection:: When a symbol appears as the car of a list,
116 we find the real function via the symbol.
117 * Function Forms:: Forms that call functions.
118 * Macro Forms:: Forms that call macros.
119 * Special Forms:: "Special forms" are idiosyncratic primitives,
120 most of them extremely important.
121 * Autoloading:: Functions set up to load files
122 containing their real definitions.
125 @node Self-Evaluating Forms
126 @subsection Self-Evaluating Forms
127 @cindex vector evaluation
128 @cindex literal evaluation
129 @cindex self-evaluating form
131 A @dfn{self-evaluating form} is any form that is not a list or
132 symbol. Self-evaluating forms evaluate to themselves: the result of
133 evaluation is the same object that was evaluated. Thus, the number 25
134 evaluates to 25, and the string @code{"foo"} evaluates to the string
135 @code{"foo"}. Likewise, evaluating a vector does not cause evaluation
136 of the elements of the vector---it returns the same vector with its
141 '123 ; @r{A number, shown without evaluation.}
145 123 ; @r{Evaluated as usual---result is the same.}
149 (eval '123) ; @r{Evaluated ``by hand''---result is the same.}
153 (eval (eval '123)) ; @r{Evaluating twice changes nothing.}
158 It is common to write numbers, characters, strings, and even vectors
159 in Lisp code, taking advantage of the fact that they self-evaluate.
160 However, it is quite unusual to do this for types that lack a read
161 syntax, because there's no way to write them textually. It is possible
162 to construct Lisp expressions containing these types by means of a Lisp
163 program. Here is an example:
167 ;; @r{Build an expression containing a buffer object.}
168 (setq print-exp (list 'print (current-buffer)))
169 @result{} (print #<buffer eval.texi>)
174 @print{} #<buffer eval.texi>
175 @result{} #<buffer eval.texi>
180 @subsection Symbol Forms
181 @cindex symbol evaluation
183 When a symbol is evaluated, it is treated as a variable. The result
184 is the variable's value, if it has one. If the symbol has no value as
185 a variable, the Lisp interpreter signals an error. For more
186 information on the use of variables, see @ref{Variables}.
188 In the following example, we set the value of a symbol with
189 @code{setq}. Then we evaluate the symbol, and get back the value that
207 The symbols @code{nil} and @code{t} are treated specially, so that the
208 value of @code{nil} is always @code{nil}, and the value of @code{t} is
209 always @code{t}; you cannot set or bind them to any other values. Thus,
210 these two symbols act like self-evaluating forms, even though
211 @code{eval} treats them like any other symbol. A symbol whose name
212 starts with @samp{:} also self-evaluates in the same way; likewise,
213 its value ordinarily cannot be changed. @xref{Constant Variables}.
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
234 @cindex indirection for functions
235 @cindex void function
237 If the first element of the list is a symbol then evaluation
238 examines the symbol's function cell, and uses its contents instead of
239 the original symbol. If the contents are another symbol, this
240 process, called @dfn{symbol function indirection}, is repeated until
241 it obtains a non-symbol. @xref{Function Names}, for more information
242 about symbol function indirection.
244 One possible consequence of this process is an infinite loop, in the
245 event that a symbol's function cell refers to the same symbol. Or a
246 symbol may have a void function cell, in which case the subroutine
247 @code{symbol-function} signals a @code{void-function} error. But if
248 neither of these things happens, we eventually obtain a non-symbol,
249 which ought to be a function or other suitable object.
251 @kindex invalid-function
252 More precisely, we should now have a Lisp function (a lambda
253 expression), a byte-code function, a primitive function, a Lisp macro,
254 a special form, or an autoload object. Each of these types is a case
255 described in one of the following sections. If the object is not one
256 of these types, Emacs signals an @code{invalid-function} error.
258 The following example illustrates the symbol indirection process. We
259 use @code{fset} to set the function cell of a symbol and
260 @code{symbol-function} to get the function cell contents
261 (@pxref{Function Cells}). Specifically, we store the symbol @code{car}
262 into the function cell of @code{first}, and the symbol @code{first} into
263 the function cell of @code{erste}.
267 ;; @r{Build this function cell linkage:}
268 ;; ------------- ----- ------- -------
269 ;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
270 ;; ------------- ----- ------- -------
273 (symbol-function 'car)
274 @result{} #<subr car>
285 (erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.}
290 By contrast, the following example calls a function without any symbol
291 function indirection, because the first element is an anonymous Lisp
292 function, not a symbol.
296 ((lambda (arg) (erste arg))
303 Executing the function itself evaluates its body; this does involve
304 symbol function indirection when calling @code{erste}.
306 This form is rarely used and is now deprecated. Instead, you should write it
311 (funcall (lambda (arg) (erste arg))
318 (let ((arg '(1 2 3))) (erste arg))
322 The built-in function @code{indirect-function} provides an easy way to
323 perform symbol function indirection explicitly.
326 @defun indirect-function function &optional noerror
327 @anchor{Definition of indirect-function}
328 This function returns the meaning of @var{function} as a function. If
329 @var{function} is a symbol, then it finds @var{function}'s function
330 definition and starts over with that value. If @var{function} is not a
331 symbol, then it returns @var{function} itself.
333 This function signals a @code{void-function} error if the final symbol
334 is unbound and optional argument @var{noerror} is @code{nil} or
335 omitted. Otherwise, if @var{noerror} is non-@code{nil}, it returns
336 @code{nil} if the final symbol is unbound.
338 It signals a @code{cyclic-function-indirection} error if there is a
339 loop in the chain of symbols.
341 Here is how you could define @code{indirect-function} in Lisp:
344 (defun indirect-function (function)
345 (if (symbolp function)
346 (indirect-function (symbol-function function))
352 @subsection Evaluation of Function Forms
353 @cindex function form evaluation
354 @cindex function call
356 If the first element of a list being evaluated is a Lisp function
357 object, byte-code object or primitive function object, then that list is
358 a @dfn{function call}. For example, here is a call to the function
365 The first step in evaluating a function call is to evaluate the
366 remaining elements of the list from left to right. The results are the
367 actual argument values, one value for each list element. The next step
368 is to call the function with this list of arguments, effectively using
369 the function @code{apply} (@pxref{Calling Functions}). If the function
370 is written in Lisp, the arguments are used to bind the argument
371 variables of the function (@pxref{Lambda Expressions}); then the forms
372 in the function body are evaluated in order, and the value of the last
373 body form becomes the value of the function call.
376 @subsection Lisp Macro Evaluation
377 @cindex macro call evaluation
379 If the first element of a list being evaluated is a macro object, then
380 the list is a @dfn{macro call}. When a macro call is evaluated, the
381 elements of the rest of the list are @emph{not} initially evaluated.
382 Instead, these elements themselves are used as the arguments of the
383 macro. The macro definition computes a replacement form, called the
384 @dfn{expansion} of the macro, to be evaluated in place of the original
385 form. The expansion may be any sort of form: a self-evaluating
386 constant, a symbol, or a list. If the expansion is itself a macro call,
387 this process of expansion repeats until some other sort of form results.
389 Ordinary evaluation of a macro call finishes by evaluating the
390 expansion. However, the macro expansion is not necessarily evaluated
391 right away, or at all, because other programs also expand macro calls,
392 and they may or may not evaluate the expansions.
394 Normally, the argument expressions are not evaluated as part of
395 computing the macro expansion, but instead appear as part of the
396 expansion, so they are computed when the expansion is evaluated.
398 For example, given a macro defined as follows:
403 (list 'car (list 'cdr x)))
408 an expression such as @code{(cadr (assq 'handler list))} is a macro
409 call, and its expansion is:
412 (car (cdr (assq 'handler list)))
416 Note that the argument @code{(assq 'handler list)} appears in the
419 @xref{Macros}, for a complete description of Emacs Lisp macros.
422 @subsection Special Forms
423 @cindex special forms
424 @cindex evaluation of special forms
426 A @dfn{special form} is a primitive function specially marked so that
427 its arguments are not all evaluated. Most special forms define control
428 structures or perform variable bindings---things which functions cannot
431 Each special form has its own rules for which arguments are evaluated
432 and which are used without evaluation. Whether a particular argument is
433 evaluated may depend on the results of evaluating other arguments.
435 If an expression's first symbol is that of a special form, the
436 expression should follow the rules of that special form; otherwise,
437 Emacs's behavior is not well-defined (though it will not crash). For
438 example, @code{((lambda (x) x . 3) 4)} contains a subexpression that
439 begins with @code{lambda} but is not a well-formed @code{lambda}
440 expression, so Emacs may signal an error, or may return 3 or 4 or
441 @code{nil}, or may behave in other ways.
443 @defun special-form-p object
444 This predicate tests whether its argument is a special form, and
445 returns @code{t} if so, @code{nil} otherwise.
448 Here is a list, in alphabetical order, of all of the special forms in
449 Emacs Lisp with a reference to where each is described.
453 @pxref{Combining Conditions}
456 @pxref{Catch and Throw}
462 @pxref{Handling Errors}
465 @pxref{Defining Variables}
468 @pxref{Defining Variables}
471 @pxref{Anonymous Functions}
477 @pxref{Interactive Call}
480 @pxref{Lambda Expressions}
484 @pxref{Local Variables}
487 @pxref{Combining Conditions}
497 @item save-current-buffer
498 @pxref{Current Buffer}
503 @item save-restriction
507 @pxref{Setting Variables}
510 @pxref{Creating Buffer-Local}
513 @pxref{Mouse Tracking}
516 @pxref{Nonlocal Exits}
522 @cindex CL note---special forms compared
524 @b{Common Lisp note:} Here are some comparisons of special forms in
525 GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and
526 @code{catch} are special forms in both Emacs Lisp and Common Lisp.
527 @code{save-excursion} is a special form in Emacs Lisp, but
528 doesn't exist in Common Lisp. @code{throw} is a special form in
529 Common Lisp (because it must be able to throw multiple values), but it
530 is a function in Emacs Lisp (which doesn't have multiple
535 @subsection Autoloading
537 The @dfn{autoload} feature allows you to call a function or macro
538 whose function definition has not yet been loaded into Emacs. It
539 specifies which file contains the definition. When an autoload object
540 appears as a symbol's function definition, calling that symbol as a
541 function automatically loads the specified file; then it calls the
542 real definition loaded from that file. The way to arrange for an
543 autoload object to appear as a symbol's function definition is
544 described in @ref{Autoload}.
549 The special form @code{quote} returns its single argument, as written,
550 without evaluating it. This provides a way to include constant symbols
551 and lists, which are not self-evaluating objects, in a program. (It is
552 not necessary to quote self-evaluating objects such as numbers, strings,
555 @defspec quote object
556 This special form returns @var{object}, without evaluating it.
559 @cindex @samp{'} for quoting
560 @cindex quoting using apostrophe
561 @cindex apostrophe for quoting
562 Because @code{quote} is used so often in programs, Lisp provides a
563 convenient read syntax for it. An apostrophe character (@samp{'})
564 followed by a Lisp object (in read syntax) expands to a list whose first
565 element is @code{quote}, and whose second element is the object. Thus,
566 the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
568 Here are some examples of expressions that use @code{quote}:
585 @result{} (quote foo)
589 @result{} (quote foo)
593 @result{} [(quote foo)]
597 Other quoting constructs include @code{function} (@pxref{Anonymous
598 Functions}), which causes an anonymous lambda expression written in Lisp
599 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
600 only part of a list, while computing and substituting other parts.
604 @cindex backquote (list substitution)
605 @cindex ` (list substitution)
608 @dfn{Backquote constructs} allow you to quote a list, but
609 selectively evaluate elements of that list. In the simplest case, it
610 is identical to the special form @code{quote}
614 (described in the previous section; @pxref{Quoting}).
616 For example, these two forms yield identical results:
620 `(a list of (+ 2 3) elements)
621 @result{} (a list of (+ 2 3) elements)
624 '(a list of (+ 2 3) elements)
625 @result{} (a list of (+ 2 3) elements)
629 @findex , @r{(with backquote)}
630 The special marker @samp{,} inside of the argument to backquote
631 indicates a value that isn't constant. The Emacs Lisp evaluator
632 evaluates the argument of @samp{,}, and puts the value in the list
637 `(a list of ,(+ 2 3) elements)
638 @result{} (a list of 5 elements)
643 Substitution with @samp{,} is allowed at deeper levels of the list
644 structure also. For example:
649 @result{} (1 2 (3 9))
653 @findex ,@@ @r{(with backquote)}
654 @cindex splicing (with backquote)
655 You can also @dfn{splice} an evaluated value into the resulting list,
656 using the special marker @samp{,@@}. The elements of the spliced list
657 become elements at the same level as the other elements of the resulting
658 list. The equivalent code without using @samp{`} is often unreadable.
659 Here are some examples:
663 (setq some-list '(2 3))
667 (cons 1 (append some-list '(4) some-list))
668 @result{} (1 2 3 4 2 3)
671 `(1 ,@@some-list 4 ,@@some-list)
672 @result{} (1 2 3 4 2 3)
676 (setq list '(hack foo bar))
677 @result{} (hack foo bar)
682 (cons 'words (append (cdr list) '(as elements)))))
683 @result{} (use the words foo bar as elements)
686 `(use the words ,@@(cdr list) as elements)
687 @result{} (use the words foo bar as elements)
695 Most often, forms are evaluated automatically, by virtue of their
696 occurrence in a program being run. On rare occasions, you may need to
697 write code that evaluates a form that is computed at run time, such as
698 after reading a form from text being edited or getting one from a
699 property list. On these occasions, use the @code{eval} function.
700 Often @code{eval} is not needed and something else should be used instead.
701 For example, to get the value of a variable, while @code{eval} works,
702 @code{symbol-value} is preferable; or rather than store expressions
703 in a property list that then need to go through @code{eval}, it is better to
704 store functions instead that are then passed to @code{funcall}.
706 The functions and variables described in this section evaluate forms,
707 specify limits to the evaluation process, or record recently returned
708 values. Loading a file also does evaluation (@pxref{Loading}).
710 It is generally cleaner and more flexible to store a function in a
711 data structure, and call it with @code{funcall} or @code{apply}, than
712 to store an expression in the data structure and evaluate it. Using
713 functions provides the ability to pass information to them as
716 @defun eval form &optional lexical
717 This is the basic function for evaluating an expression. It evaluates
718 @var{form} in the current environment and returns the result. How the
719 evaluation proceeds depends on the type of the object (@pxref{Forms}).
721 The argument @var{lexical}, if non-@code{nil}, means to evaluate
722 @var{form} using lexical scoping rules for variables, instead of the
723 default dynamic scoping rules. @xref{Lexical Binding}.
725 Since @code{eval} is a function, the argument expression that appears
726 in a call to @code{eval} is evaluated twice: once as preparation before
727 @code{eval} is called, and again by the @code{eval} function itself.
738 ;; @r{Here @code{eval} receives argument @code{foo}}
741 ;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}
747 The number of currently active calls to @code{eval} is limited to
748 @code{max-lisp-eval-depth} (see below).
751 @deffn Command eval-region start end &optional stream read-function
752 @anchor{Definition of eval-region}
753 This function evaluates the forms in the current buffer in the region
754 defined by the positions @var{start} and @var{end}. It reads forms from
755 the region and calls @code{eval} on them until the end of the region is
756 reached, or until an error is signaled and not handled.
758 By default, @code{eval-region} does not produce any output. However,
759 if @var{stream} is non-@code{nil}, any output produced by output
760 functions (@pxref{Output Functions}), as well as the values that
761 result from evaluating the expressions in the region are printed using
762 @var{stream}. @xref{Output Streams}.
764 If @var{read-function} is non-@code{nil}, it should be a function,
765 which is used instead of @code{read} to read expressions one by one.
766 This function is called with one argument, the stream for reading
767 input. You can also use the variable @code{load-read-function}
768 (@pxref{Definition of load-read-function,, How Programs Do Loading})
769 to specify this function, but it is more robust to use the
770 @var{read-function} argument.
772 @code{eval-region} does not move point. It always returns @code{nil}.
775 @cindex evaluation of buffer contents
776 @deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
777 This is similar to @code{eval-region}, but the arguments provide
778 different optional features. @code{eval-buffer} operates on the
779 entire accessible portion of buffer @var{buffer-or-name}.
780 @var{buffer-or-name} can be a buffer, a buffer name (a string), or
781 @code{nil} (or omitted), which means to use the current buffer.
782 @var{stream} is used as in @code{eval-region}, unless @var{stream} is
783 @code{nil} and @var{print} non-@code{nil}. In that case, values that
784 result from evaluating the expressions are still discarded, but the
785 output of the output functions is printed in the echo area.
786 @var{filename} is the file name to use for @code{load-history}
787 (@pxref{Unloading}), and defaults to @code{buffer-file-name}
788 (@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil},
789 @code{read} converts strings to unibyte whenever possible.
791 @findex eval-current-buffer
792 @code{eval-current-buffer} is an alias for this command.
795 @defopt max-lisp-eval-depth
796 @anchor{Definition of max-lisp-eval-depth}
797 This variable defines the maximum depth allowed in calls to @code{eval},
798 @code{apply}, and @code{funcall} before an error is signaled (with error
799 message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).
801 This limit, with the associated error when it is exceeded, is one way
802 Emacs Lisp avoids infinite recursion on an ill-defined function. If
803 you increase the value of @code{max-lisp-eval-depth} too much, such
804 code can cause stack overflow instead.
805 @cindex Lisp nesting error
807 The depth limit counts internal uses of @code{eval}, @code{apply}, and
808 @code{funcall}, such as for calling the functions mentioned in Lisp
809 expressions, and recursive evaluation of function call arguments and
810 function body forms, as well as explicit calls in Lisp code.
812 The default value of this variable is 400. If you set it to a value
813 less than 100, Lisp will reset it to 100 if the given value is
814 reached. Entry to the Lisp debugger increases the value, if there is
815 little room left, to make sure the debugger itself has room to
818 @code{max-specpdl-size} provides another limit on nesting.
819 @xref{Definition of max-specpdl-size,, Local Variables}.
823 The value of this variable is a list of the values returned by all the
824 expressions that were read, evaluated, and printed from buffers
825 (including the minibuffer) by the standard Emacs commands which do
826 this. (Note that this does @emph{not} include evaluation in
827 @file{*ielm*} buffers, nor evaluation using @kbd{C-j} in
828 @code{lisp-interaction-mode}.) The elements are ordered most recent
837 (list 'A (1+ 2) auto-save-default)
842 @result{} ((A 3 t) 1 @dots{})
846 This variable is useful for referring back to values of forms recently
847 evaluated. It is generally a bad idea to print the value of
848 @code{values} itself, since this may be very long. Instead, examine
849 particular elements, like this:
853 ;; @r{Refer to the most recent evaluation result.}
858 ;; @r{That put a new element on,}
859 ;; @r{so all elements move back one.}
864 ;; @r{This gets the element that was next-to-most-recent}
865 ;; @r{before this example.}