@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions.@setfilename ../info/eval@node Evaluation, Control Structures, Symbols, Top@chapter Evaluation@cindex evaluation@cindex interpreter@cindex interpreter@cindex value of expression The @dfn{evaluation} of expressions in Emacs Lisp is performed by the@dfn{Lisp interpreter}---a program that receives a Lisp object as inputand computes its @dfn{value as an expression}. How it does this dependson the data type of the object, according to rules described in thischapter. The interpreter runs automatically to evaluate portions ofyour program, but can also be called explicitly via the Lisp primitivefunction @code{eval}.@ifnottex@menu* Intro Eval:: Evaluation in the scheme of things.* Forms:: How various sorts of objects are evaluated.* Quoting:: Avoiding evaluation (to put constants in the program).* Eval:: How to invoke the Lisp interpreter explicitly.@end menu@node Intro Eval@section Introduction to Evaluation The Lisp interpreter, or evaluator, is the program that computesthe value of an expression that is given to it. When a function written in Lisp is called, the evaluator computes the value of thefunction by evaluating the expressions in the function body. Thus,running any Lisp program really means running the Lisp interpreter. How the evaluator handles an object depends primarily on the datatype of the object.@end ifnottex@cindex forms@cindex expression A Lisp object that is intended for evaluation is called an@dfn{expression} or a @dfn{form}. The fact that expressions are dataobjects and not merely text is one of the fundamental differencesbetween Lisp-like languages and typical programming languages. Anyobject can be evaluated, but in practice only numbers, symbols, listsand strings are evaluated very often. It is very common to read a Lisp expression and then evaluate theexpression, but reading and evaluation are separate activities, andeither can be performed alone. Reading per se does not evaluateanything; it converts the printed representation of a Lisp object to theobject itself. It is up to the caller of @code{read} whether thisobject is a form to be evaluated, or serves some entirely differentpurpose. @xref{Input Functions}. Do not confuse evaluation with command key interpretation. Theeditor command loop translates keyboard input into a command (aninteractively callable function) using the active keymaps, and thenuses @code{call-interactively} to invoke the command. The execution ofthe command itself involves evaluation if the command is written inLisp, but that is not a part of command key interpretation itself.@xref{Command Loop}.@cindex recursive evaluation Evaluation is a recursive process. That is, evaluation of a form maycall @code{eval} to evaluate parts of the form. For example, evaluationof a function call first evaluates each argument of the function call,and then evaluates each form in the function body. Consider evaluationof the form @code{(car x)}: the subform @code{x} must first be evaluatedrecursively, so that its value can be passed as an argument to thefunction @code{car}. Evaluation of a function call ultimately calls the function specifiedin it. @xref{Functions}. The execution of the function may itself workby evaluating the function definition; or the function may be a Lispprimitive implemented in C, or it may be a byte-compiled function(@pxref{Byte Compilation}).@cindex environment The evaluation of forms takes place in a context called the@dfn{environment}, which consists of the current values and bindings ofall Lisp variables.@footnote{This definition of ``environment'' isspecifically not intended to include all the data that can affect theresult of a program.} Whenever a form refers to a variable withoutcreating a new binding for it, the value of the variable's binding inthe current environment is used. @xref{Variables}.@cindex side effect Evaluation of a form may create new environments for recursiveevaluation by binding variables (@pxref{Local Variables}). Theseenvironments are temporary and vanish by the time evaluation of the formis complete. The form may also make changes that persist; these changesare called @dfn{side effects}. An example of a form that produces sideeffects is @code{(setq foo 1)}. The details of what evaluation means for each kind of form aredescribed below (@pxref{Forms}).@node Forms@section Kinds of Forms A Lisp object that is intended to be evaluated is called a @dfn{form}.How Emacs evaluates a form depends on its data type. Emacs has threedifferent kinds of form that are evaluated differently: symbols, lists,and ``all other types''. This section describes all three kinds, one byone, starting with the ``all other types'' which are self-evaluatingforms.@menu* Self-Evaluating Forms:: Forms that evaluate to themselves.* Symbol Forms:: Symbols evaluate as variables.* Classifying Lists:: How to distinguish various sorts of list forms.* Function Indirection:: When a symbol appears as the car of a list, we find the real function via the symbol.* Function Forms:: Forms that call functions.* Macro Forms:: Forms that call macros.* Special Forms:: ``Special forms'' are idiosyncratic primitives, most of them extremely important.* Autoloading:: Functions set up to load files containing their real definitions.@end menu@node Self-Evaluating Forms@subsection Self-Evaluating Forms@cindex vector evaluation@cindex literal evaluation@cindex self-evaluating form A @dfn{self-evaluating form} is any form that is not a list or symbol.Self-evaluating forms evaluate to themselves: the result of evaluationis the same object that was evaluated. Thus, the number 25 evaluates to25, and the string @code{"foo"} evaluates to the string @code{"foo"}.Likewise, evaluation of a vector does not cause evaluation of theelements of the vector---it returns the same vector with its contentsunchanged.@example@group'123 ; @r{A number, shown without evaluation.} @result{} 123@end group@group123 ; @r{Evaluated as usual---result is the same.} @result{} 123@end group@group(eval '123) ; @r{Evaluated ``by hand''---result is the same.} @result{} 123@end group@group(eval (eval '123)) ; @r{Evaluating twice changes nothing.} @result{} 123@end group@end example It is common to write numbers, characters, strings, and even vectorsin Lisp code, taking advantage of the fact that they self-evaluate.However, it is quite unusual to do this for types that lack a readsyntax, because there's no way to write them textually. It is possibleto construct Lisp expressions containing these types by means of a Lispprogram. Here is an example:@example@group;; @r{Build an expression containing a buffer object.}(setq print-exp (list 'print (current-buffer))) @result{} (print #<buffer eval.texi>)@end group@group;; @r{Evaluate it.}(eval print-exp) @print{} #<buffer eval.texi> @result{} #<buffer eval.texi>@end group@end example@node Symbol Forms@subsection Symbol Forms@cindex symbol evaluation When a symbol is evaluated, it is treated as a variable. The resultis the variable's value, if it has one. If it has none (if its valuecell is void), an error is signaled. For more information on the use ofvariables, see @ref{Variables}. In the following example, we set the value of a symbol with@code{setq}. Then we evaluate the symbol, and get back the value that@code{setq} stored.@example@group(setq a 123) @result{} 123@end group@group(eval 'a) @result{} 123@end group@groupa @result{} 123@end group@end example The symbols @code{nil} and @code{t} are treated specially, so that thevalue of @code{nil} is always @code{nil}, and the value of @code{t} isalways @code{t}; you cannot set or bind them to any other values. Thus,these two symbols act like self-evaluating forms, even though@code{eval} treats them like any other symbol. A symbol whose namestarts with @samp{:} also self-evaluates in the same way; likewise,its value ordinarily cannot be changed. @xref{Constant Variables}.@node Classifying Lists@subsection Classification of List Forms@cindex list form evaluation A form that is a nonempty list is either a function call, a macrocall, or a special form, according to its first element. These threekinds of forms are evaluated in different ways, described below. Theremaining list elements constitute the @dfn{arguments} for the function,macro, or special form. The first step in evaluating a nonempty list is to examine its firstelement. This element alone determines what kind of form the list isand how the rest of the list is to be processed. The first element is@emph{not} evaluated, as it would be in some Lisp dialects such asScheme.@node Function Indirection@subsection Symbol Function Indirection@cindex symbol function indirection@cindex indirection@cindex void function If the first element of the list is a symbol then evaluation examinesthe symbol's function cell, and uses its contents instead of theoriginal symbol. If the contents are another symbol, this process,called @dfn{symbol function indirection}, is repeated until it obtains anon-symbol. @xref{Function Names}, for more information about using asymbol as a name for a function stored in the function cell of thesymbol. One possible consequence of this process is an infinite loop, in theevent that a symbol's function cell refers to the same symbol. Or asymbol may have a void function cell, in which case the subroutine@code{symbol-function} signals a @code{void-function} error. But ifneither of these things happens, we eventually obtain a non-symbol,which ought to be a function or other suitable object.@kindex invalid-function@cindex invalid function More precisely, we should now have a Lisp function (a lambdaexpression), a byte-code function, a primitive function, a Lisp macro, aspecial form, or an autoload object. Each of these types is a casedescribed in one of the following sections. If the object is not one ofthese types, the error @code{invalid-function} is signaled. The following example illustrates the symbol indirection process. Weuse @code{fset} to set the function cell of a symbol and@code{symbol-function} to get the function cell contents(@pxref{Function Cells}). Specifically, we store the symbol @code{car}into the function cell of @code{first}, and the symbol @code{first} intothe function cell of @code{erste}.@smallexample@group;; @r{Build this function cell linkage:};; ------------- ----- ------- -------;; | #<subr car> | <-- | car | <-- | first | <-- | erste |;; ------------- ----- ------- -------@end group@end smallexample@smallexample@group(symbol-function 'car) @result{} #<subr car>@end group@group(fset 'first 'car) @result{} car@end group@group(fset 'erste 'first) @result{} first@end group@group(erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.} @result{} 1@end group@end smallexample By contrast, the following example calls a function without any symbolfunction indirection, because the first element is an anonymous Lispfunction, not a symbol.@smallexample@group((lambda (arg) (erste arg)) '(1 2 3)) @result{} 1@end group@end smallexample@noindentExecuting the function itself evaluates its body; this does involvesymbol function indirection when calling @code{erste}. The built-in function @code{indirect-function} provides an easy way toperform symbol function indirection explicitly.@c Emacs 19 feature@defun indirect-function functionThis function returns the meaning of @var{function} as a function. If@var{function} is a symbol, then it finds @var{function}'s functiondefinition and starts over with that value. If @var{function} is not asymbol, then it returns @var{function} itself.Here is how you could define @code{indirect-function} in Lisp:@smallexample(defun indirect-function (function) (if (symbolp function) (indirect-function (symbol-function function)) function))@end smallexample@end defun@node Function Forms@subsection Evaluation of Function Forms@cindex function form evaluation@cindex function call If the first element of a list being evaluated is a Lisp functionobject, byte-code object or primitive function object, then that list isa @dfn{function call}. For example, here is a call to the function@code{+}:@example(+ 1 x)@end example The first step in evaluating a function call is to evaluate theremaining elements of the list from left to right. The results are theactual argument values, one value for each list element. The next stepis to call the function with this list of arguments, effectively usingthe function @code{apply} (@pxref{Calling Functions}). If the functionis written in Lisp, the arguments are used to bind the argumentvariables of the function (@pxref{Lambda Expressions}); then the formsin the function body are evaluated in order, and the value of the lastbody form becomes the value of the function call.@node Macro Forms@subsection Lisp Macro Evaluation@cindex macro call evaluation If the first element of a list being evaluated is a macro object, thenthe list is a @dfn{macro call}. When a macro call is evaluated, theelements of the rest of the list are @emph{not} initially evaluated.Instead, these elements themselves are used as the arguments of themacro. The macro definition computes a replacement form, called the@dfn{expansion} of the macro, to be evaluated in place of the originalform. The expansion may be any sort of form: a self-evaluatingconstant, a symbol, or a list. If the expansion is itself a macro call,this process of expansion repeats until some other sort of form results. Ordinary evaluation of a macro call finishes by evaluating theexpansion. However, the macro expansion is not necessarily evaluatedright away, or at all, because other programs also expand macro calls,and they may or may not evaluate the expansions. Normally, the argument expressions are not evaluated as part ofcomputing the macro expansion, but instead appear as part of theexpansion, so they are computed when the expansion is evaluated. For example, given a macro defined as follows:@example@group(defmacro cadr (x) (list 'car (list 'cdr x)))@end group@end example@noindentan expression such as @code{(cadr (assq 'handler list))} is a macrocall, and its expansion is:@example(car (cdr (assq 'handler list)))@end example@noindentNote that the argument @code{(assq 'handler list)} appears in theexpansion.@xref{Macros}, for a complete description of Emacs Lisp macros.@node Special Forms@subsection Special Forms@cindex special form evaluation A @dfn{special form} is a primitive function specially marked so thatits arguments are not all evaluated. Most special forms define controlstructures or perform variable bindings---things which functions cannotdo. Each special form has its own rules for which arguments are evaluatedand which are used without evaluation. Whether a particular argument isevaluated may depend on the results of evaluating other arguments. Here is a list, in alphabetical order, of all of the special forms inEmacs Lisp with a reference to where each is described.@table @code@item and@pxref{Combining Conditions}@item catch@pxref{Catch and Throw}@item cond@pxref{Conditionals}@item condition-case@pxref{Handling Errors}@item defconst@pxref{Defining Variables}@item defmacro@pxref{Defining Macros}@item defun@pxref{Defining Functions}@item defvar@pxref{Defining Variables}@item function@pxref{Anonymous Functions}@item if@pxref{Conditionals}@item interactive@pxref{Interactive Call}@item let@itemx let*@pxref{Local Variables}@item or@pxref{Combining Conditions}@item prog1@itemx prog2@itemx progn@pxref{Sequencing}@item quote@pxref{Quoting}@item save-current-buffer@pxref{Current Buffer}@item save-excursion@pxref{Excursions}@item save-restriction@pxref{Narrowing}@item save-window-excursion@pxref{Window Configurations}@item setq@pxref{Setting Variables}@item setq-default@pxref{Creating Buffer-Local}@item track-mouse@pxref{Mouse Tracking}@item unwind-protect@pxref{Nonlocal Exits}@item while@pxref{Iteration}@item with-output-to-temp-buffer@pxref{Temporary Displays}@end table@cindex CL note---special forms compared@quotation@b{Common Lisp note:} Here are some comparisons of special forms inGNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and@code{catch} are special forms in both Emacs Lisp and Common Lisp.@code{defun} is a special form in Emacs Lisp, but a macro in CommonLisp. @code{save-excursion} is a special form in Emacs Lisp, butdoesn't exist in Common Lisp. @code{throw} is a special form inCommon Lisp (because it must be able to throw multiple values), but itis a function in Emacs Lisp (which doesn't have multiplevalues).@refill@end quotation@node Autoloading@subsection Autoloading The @dfn{autoload} feature allows you to call a function or macrowhose function definition has not yet been loaded into Emacs. Itspecifies which file contains the definition. When an autoload objectappears as a symbol's function definition, calling that symbol as afunction automatically loads the specified file; then it calls the realdefinition loaded from that file. @xref{Autoload}.@node Quoting@section Quoting@cindex quoting The special form @code{quote} returns its single argument, as written,without evaluating it. This provides a way to include constant symbolsand lists, which are not self-evaluating objects, in a program. (It isnot necessary to quote self-evaluating objects such as numbers, strings,and vectors.)@defspec quote objectThis special form returns @var{object}, without evaluating it.@end defspec@cindex @samp{'} for quoting@cindex quoting using apostrophe@cindex apostrophe for quotingBecause @code{quote} is used so often in programs, Lisp provides aconvenient read syntax for it. An apostrophe character (@samp{'})followed by a Lisp object (in read syntax) expands to a list whose firstelement is @code{quote}, and whose second element is the object. Thus,the read syntax @code{'x} is an abbreviation for @code{(quote x)}.Here are some examples of expressions that use @code{quote}:@example@group(quote (+ 1 2)) @result{} (+ 1 2)@end group@group(quote foo) @result{} foo@end group@group'foo @result{} foo@end group@group''foo @result{} (quote foo)@end group@group'(quote foo) @result{} (quote foo)@end group@group['foo] @result{} [(quote foo)]@end group@end example Other quoting constructs include @code{function} (@pxref{AnonymousFunctions}), which causes an anonymous lambda expression written in Lispto be compiled, and @samp{`} (@pxref{Backquote}), which is used to quoteonly part of a list, while computing and substituting other parts.@node Eval@section Eval Most often, forms are evaluated automatically, by virtue of theiroccurrence in a program being run. On rare occasions, you may need towrite code that evaluates a form that is computed at run time, such asafter reading a form from text being edited or getting one from aproperty list. On these occasions, use the @code{eval} function. The functions and variables described in this section evaluate forms,specify limits to the evaluation process, or record recently returnedvalues. Loading a file also does evaluation (@pxref{Loading}). @strong{Note:} it is generally cleaner and more flexible to store afunction in a data structure, and call it with @code{funcall} or@code{apply}, than to store an expression in the data structure andevaluate it. Using functions provides the ability to pass informationto them as arguments.@defun eval formThis is the basic function evaluating an expression. It evaluates@var{form} in the current environment and returns the result. How theevaluation proceeds depends on the type of the object (@pxref{Forms}).Since @code{eval} is a function, the argument expression that appearsin a call to @code{eval} is evaluated twice: once as preparation before@code{eval} is called, and again by the @code{eval} function itself.Here is an example:@example@group(setq foo 'bar) @result{} bar@end group@group(setq bar 'baz) @result{} baz;; @r{Here @code{eval} receives argument @code{foo}}(eval 'foo) @result{} bar;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}(eval foo) @result{} baz@end group@end exampleThe number of currently active calls to @code{eval} is limited to@code{max-lisp-eval-depth} (see below).@end defun@deffn Command eval-region start end &optional stream read-functionThis function evaluates the forms in the current buffer in the regiondefined by the positions @var{start} and @var{end}. It reads forms fromthe region and calls @code{eval} on them until the end of the region isreached, or until an error is signaled and not handled.If @var{stream} is non-@code{nil}, the values that result fromevaluating the expressions in the region are printed using @var{stream}.@xref{Output Streams}.If @var{read-function} is non-@code{nil}, it should be a function, whichis used instead of @code{read} to read expressions one by one. Thisfunction is called with one argument, the stream for reading input. Youcan also use the variable @code{load-read-function} (@pxref{How ProgramsDo Loading}) to specify this function, but it is more robust to use the@var{read-function} argument.@code{eval-region} always returns @code{nil}.@end deffn@cindex evaluation of buffer contents@deffn Command eval-current-buffer &optional streamThis is like @code{eval-region} except that it operates on the wholebuffer.@end deffn@defvar max-lisp-eval-depthThis variable defines the maximum depth allowed in calls to @code{eval},@code{apply}, and @code{funcall} before an error is signaled (with errormessage @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This limit,with the associated error when it is exceeded, is one way that Lispavoids infinite recursion on an ill-defined function.@cindex Lisp nesting errorThe depth limit counts internal uses of @code{eval}, @code{apply}, and@code{funcall}, such as for calling the functions mentioned in Lispexpressions, and recursive evaluation of function call arguments andfunction body forms, as well as explicit calls in Lisp code.The default value of this variable is 300. If you set it to a valueless than 100, Lisp will reset it to 100 if the given value is reached.Entry to the Lisp debugger increases the value, if there is little roomleft, to make sure the debugger itself has room to execute.@code{max-specpdl-size} provides another limit on nesting.@xref{Local Variables}.@end defvar@defvar valuesThe value of this variable is a list of the values returned by all theexpressions that were read, evaluated, and printed from buffers(including the minibuffer) by the standard Emacs commands which do this.The elements are ordered most recent first.@example@group(setq x 1) @result{} 1@end group@group(list 'A (1+ 2) auto-save-default) @result{} (A 3 t)@end group@groupvalues @result{} ((A 3 t) 1 @dots{})@end group@end exampleThis variable is useful for referring back to values of forms recentlyevaluated. It is generally a bad idea to print the value of@code{values} itself, since this may be very long. Instead, examineparticular elements, like this:@example@group;; @r{Refer to the most recent evaluation result.}(nth 0 values) @result{} (A 3 t)@end group@group;; @r{That put a new element on,};; @r{so all elements move back one.}(nth 1 values) @result{} (A 3 t)@end group@group;; @r{This gets the element that was next-to-most-recent};; @r{before this example.}(nth 3 values) @result{} 1@end group@end example@end defvar