@c -*-texinfo-*-
@setfilename ../info/eval
@node Evaluation, Control Structures, Symbols, Top
@chapter Evaluation
@cindex evaluation
@cindex Lisp 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 input
and computes its @dfn{value as an expression}.  The value is computed in
a fashion that depends on the data type of the object, following rules
described in this chapter.  The interpreter runs automatically
to evaluate portions of your program, but can also be called explicitly
via the Lisp primitive function @code{eval}.

@ifinfo
@menu
* Intro Eval::  Evaluation in the scheme of things.
* Eval::        How to invoke the Lisp interpreter explicitly.
* Forms::       How various sorts of objects are evaluated.
* Quoting::     Avoiding evaluation (to put constants in the program).
@end menu

@node Intro Eval, Eval, Evaluation, Evaluation
@section Introduction to Evaluation

  The Lisp interpreter, or evaluator, is the program which computes
the value of an expression which is given to it.  When a function 
written in Lisp is called, the evaluator computes the value of the
function 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 data
type of the object.
@end ifinfo

@cindex forms
@cindex expression
  A Lisp object which is intended for evaluation is called an
@dfn{expression} or a @dfn{form}.  The fact that expressions are data
objects and not merely text is one of the fundamental differences
between Lisp-like languages and typical programming languages.  Any
object can be evaluated, but in practice only numbers, symbols, lists
and strings are evaluated very often.

  It is very common to read a Lisp expression and then evaluate the
expression, but reading and evaluation are separate activities, and
either can be performed alone.  Reading per se does not evaluate
anything; it converts the printed representation of a Lisp object to the
object itself.  It is up to the caller of @code{read} whether this
object is a form to be evaluated, or serves some entirely different
purpose.  @xref{Input Functions}.

  Do not confuse evaluation with command key interpretation.  The
editor command loop translates keyboard input into a command (an
interactively callable function) using the current keymaps, and then
uses @code{call-interactively} to invoke the command.  The execution of
the command itself involves evaluation if the command is written in
Lisp, 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 may
cause @code{eval} to be called again in order to evaluate parts of the
form.  For example, evaluation of a function call first evaluates each
argument of the function call, and then evaluates each form in the
function body.  Consider evaluation of the form @code{(car x)}: the
subform @code{x} must first be evaluated recursively, so that its value
can be passed as an argument to the function @code{car}.

@cindex environment
  The evaluation of forms takes place in a context called the
@dfn{environment}, which consists of the current values and bindings of
all Lisp variables.  Whenever the form refers to a variable without
creating a new binding for it, the value of the current binding is used.
@xref{Variables}.

@cindex side effect
  Evaluation of a form may create new environments for recursive
evaluation by binding variables (@pxref{Local Variables}).  These
environments are temporary and will be gone by the time evaluation of
the form is complete.  The form may also make changes that persist;
these changes are called @dfn{side-effects}.  An example of a form that
produces side-effects is @code{(setq foo 1)}.

  Finally, evaluation of one particular function call, @code{byte-code},
invokes the @dfn{byte-code interpreter} on its arguments.  Although the
byte-code interpreter is not the same as the Lisp interpreter, it uses
the same environment as the Lisp interpreter, and may on occasion invoke
the Lisp interpreter.  (@xref{Byte Compilation}.)

  The details of what evaluation means for each kind of form are
described below (@pxref{Forms}).

@node Eval, Forms, Intro Eval, Evaluation
@section Eval

  Most often, forms are evaluated automatically, by virtue of their
occurrence in a program being run.  On rare occasions, you may need
to write code that evaluates a form that is computed at run time, such
as when the form is read from text being edited or found on a property
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
returned values.  Evaluation is also performed by @code{load}
(@pxref{Loading}).

@defun eval form
  This is the basic function for performing evaluation.  It evaluates
@var{form} in the current environment and returns the result.  How the
evaluation proceeds depends on the type of the object (@pxref{Forms}).

  Since @code{eval} is a function, the argument expression that appears
in 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
(setq foo 'bar)
     @result{} bar
(setq bar 'baz)
     @result{} baz
;; @r{@code{eval} is called on the form @code{bar}, which is the value of @code{foo}}
(eval foo)
     @result{} baz
@end example

  The number of currently active calls to @code{eval} is limited to
@code{max-lisp-eval-depth}.
@end defun

@cindex evaluation of buffer contents
@deffn Command eval-current-buffer &optional stream
  This function evaluates the forms in the current buffer.  It reads
forms from the buffer and calls @code{eval} on them until the end of the
buffer is reached, or until an error is signaled and not handled.

  If @var{stream} is supplied, the variable @code{standard-output} is
bound to @var{stream} during the evaluation (@pxref{Output
Functions}).

@code{eval-current-buffer} always returns @code{nil}.
@end deffn

@deffn Command eval-region start end &optional stream
  This function evaluates the forms in the current buffer in the region
defined by the positions @var{start} and @var{end}.  It reads forms from
the region and calls @code{eval} on them until the end of the region is
reached, or until an error is signaled and not handled.

  If @var{stream} is supplied, @code{standard-output} is bound to it
for the duration of the command.

@code{eval-region} always returns @code{nil}.
@end deffn

@defvar max-lisp-eval-depth
  This variable defines the maximum depth allowed in calls to
@code{eval}, @code{apply}, and @code{funcall} before an error is
signaled (with error message @code{"Lisp nesting exceeds
max-lisp-eval-depth"}).  @code{eval} is called recursively to evaluate
the arguments of Lisp function calls and to evaluate bodies of
functions.

  This limit, with the associated error when it is exceeded, is one way
that Lisp avoids infinite recursion on an ill-defined function.
@cindex Lisp nesting error

  The default value of this variable is 200.  If you set it to a value
less than 100, Lisp will reset it to 100 if the given value is reached.
@end defvar

@defvar values
  The value of this variable is a list of values returned by all
expressions which were read from buffers (including the minibuffer),
evaluated, and printed.  The elements are in order, most recent first.

@example
(setq x 1)
     @result{} 1
(list 'A (1+ 2) auto-save-default)
     @result{} (A 3 t)
values
     @result{} ((A 3 t) 1 @dots{})
@end example

This variable is useful for referring back to values of forms recently
evaluated.  It is generally a bad idea to print the value of
@code{values} itself, since this may be very long.  Instead, examine
particular elements, like this:

@example
;; @r{Refer to the most recent evaluation result.}
(nth 0 values)
     @result{} (A 3 t)
;; @r{That put a new element on, so all elements move back one.}
(nth 1 values)
     @result{} (A 3 t)
;; @r{This gets the element that was next-to-last before this example.}
(nth 3 values)
     @result{} 1
@end example
@end defvar

@node Forms, Quoting, Eval, Evaluation
@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 three
different kinds of form that are evaluated differently: symbols, lists,
and ``all other types''.  All three kinds are described in this section,
starting with ``all other types'' which are self-evaluating forms.

@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 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, Symbol Forms, Forms, 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 evaluation
is the same object that was evaluated.  Thus, the number 25 evaluates to
25, and the string @code{"foo"} evaluates to the string @code{"foo"}.
Likewise, evaluation of a vector does not cause evaluation of the
elements of the vector---it returns the same vector with its contents
unchanged.

@example
'123               ; @r{An object, shown without evaluation.}
     @result{} 123
123                ; @r{Evaluated as usual---result is the same.}
     @result{} 123
(eval '123)        ; @r{Evaluated ``by hand''---result is the same.}
     @result{} 123
(eval (eval '123)) ; @r{Evaluating twice changes nothing.}
     @result{} 123
@end example

  It is common to write numbers, characters, strings, and even vectors
in Lisp code, taking advantage of the fact that they self-evaluate.
However, it is quite unusual to do this for types that lack a read
syntax, because it is inconvenient and not very useful; however, it is
possible to put them inside Lisp programs when they are constructed
from subexpressions rather than read.  Here is an example:

@example
;; @r{Build such an expression.}
(setq buffer (list 'print (current-buffer)))
     @result{} (print #<buffer eval.texi>)
;; @r{Evaluate it.}
(eval buffer)
     @print{} #<buffer eval.texi>
     @result{} #<buffer eval.texi>
@end example

@node Symbol Forms, Classifying Lists, Self-Evaluating Forms, Forms
@subsection Symbol Forms
@cindex symbol evaluation

  When a symbol is evaluated, it is treated as a variable.  The result
is the variable's value, if it has one.  If it has none (if its value
cell is void), an error is signaled.  For more information on the use of
variables, see @ref{Variables}.

  In the following example, the value of a symbol is set with
@code{setq}.  When the symbol is later evaluated, that value is
returned.

@example
(setq a 123)
     @result{} 123
(eval 'a)
     @result{} 123
a
     @result{} 123
@end example

  The symbols @code{nil} and @code{t} are treated specially, so that the
value of @code{nil} is always @code{nil}, and the value of @code{t} is
always @code{t}.  Thus, these two symbols act like self-evaluating
forms, even though @code{eval} treats them like any other symbol.

@node Classifying Lists, Function Forms, Symbol Forms, Forms
@subsection Classification of List Forms
@cindex list form evaluation

  A form that is a nonempty list is either a function call, a macro
call, or a special form, according to its first element.  These three
kinds of forms are evaluated in different ways, described below.  The
rest of the list consists of @dfn{arguments} for the function, macro
or special form.

  The first step in evaluating a nonempty list is to examine its first
element.  This element alone determines what kind of form the list is
and 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 including
Scheme.

@cindex symbol function indirection
@cindex indirection
@kindex void-function
@cindex void function
  If the first element of the list is a symbol, as it most commonly is,
then the symbol's function cell is examined, and its contents are used
instead of the original symbol.  If the contents are another symbol,
this process, called @dfn{symbol function indirection}, is repeated
until a non-symbol is obtained.

  One possible consequence of this process is an infinite loop, in the
event that a symbol's function cell refers to the same symbol.  Or a
symbol may have a void function cell, causing a @code{void-function}
error.  But if neither 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 lambda
expression), a primitive function, a Lisp macro, a special form, or an
autoload object.  Each of these types is a case described in one of
the following sections.  If the object is not one of these types, the
error @code{invalid-function} is signaled.

  The following example illustrates the symbol indirection process.  We
use @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} into
the function cell of @code{erste}.

@example
@group
;; @r{Build this function cell linkage:}
;;    -------------       -----        -------        -------
;;   | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
;;    -------------       -----        -------        -------
@end group

(symbol-function 'car)
     @result{} #<subr car>
(fset 'first 'car)
     @result{} car
(fset 'erste 'first)
     @result{} first
@group
(erste '(1 2 3))           ; @r{Call the function referenced by @code{erste}.}
     @result{} 1
@end group
@end example

  By contrast, the following example calls a function without any symbol
function indirection, because the first element is an anonymous Lisp
function, not a symbol.

@example
((lambda (arg) (erste arg))
 '(1 2 3)) 
     @result{} 1
@end example

@noindent
After that function is called, its body is evaluated; this does
involve symbol function indirection when calling @code{erste}.

@node Function Forms, Macro Forms, Classifying Lists, 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 function
object or primitive function object, then that list is a @dfn{function
call}.  For example, here is a call to the function @code{+}:

@example
(+ 1 x)
@end example

  When a function call is evaluated, the first step is to evaluate the
remaining elements of the list in the order they appear.  The results
are the actual argument values, one argument from each element.  Then
the function is called with this list of arguments, effectively using
the function @code{apply} (@pxref{Calling Functions}).  If the function
is written in Lisp, the arguments are used to bind the argument
variables of the function (@pxref{Lambda Expressions}); then the forms
in the function body are evaluated in order, and the result of the last
one is used as the value of the function call.

@node Macro Forms, Special Forms, Function Forms, Forms
@subsection Lisp Macro Evaluation
@cindex macro call evaluation

  If the first element of a list being evaluated is a macro object, then
the list is a @dfn{macro call}.  When a macro call is evaluated, the
elements of the rest of the list are @emph{not} initially evaluated.
Instead, these elements themselves are used as the arguments of the
macro.  The macro definition computes a replacement form, called the
@dfn{expansion} of the macro, which is evaluated in place of the
original form.  The expansion may be any sort of form: a self-evaluating
constant, 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.

  Normally, the argument expressions are not evaluated as part of
computing the macro expansion, but instead appear as part of the
expansion, so they are evaluated when the expansion is evaluated.

  For example, given a macro defined as follows:

@example
(defmacro cadr (x)
  (list 'car (list 'cdr x)))
@end example

@noindent
an expression such as @code{(cadr (assq 'handler list))} is a macro
call, and its expansion is:

@example
(car (cdr (assq 'handler list)))
@end example

@noindent
Note that the argument @code{(assq 'handler list)} appears in the
expansion.

@xref{Macros}, for a complete description of Emacs Lisp macros.

@node Special Forms, Autoloading, Macro Forms, Forms
@subsection Special Forms
@cindex special form evaluation

  A @dfn{special form} is a primitive function specially marked so
that its arguments are not all evaluated.  Special forms define
control structures or perform variable bindings---things which
functions cannot do.

  Each special form has its own rules for which arguments are evaluated
and which are used without evaluation.  Whether a particular argument is
evaluated may depend on the results of evaluating other arguments.

  Here is a list, in alphabetical order, of all of the special forms in
Emacs 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{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
@pxref{Local Variables}

@item let*
@pxref{Local Variables}

@item or
@pxref{Combining Conditions}

@item prog1
@pxref{Sequencing}

@item prog2
@pxref{Sequencing}

@item progn
@pxref{Sequencing}

@item quote
@pxref{Quoting}

@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 unwind-protect
@pxref{Nonlocal Exits}

@item while
@pxref{Iteration}

@item with-output-to-temp-buffer
@pxref{Temporary Displays}
@end table

@quotation
@b{Common Lisp note:} here are some comparisons of special forms in
GNU 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 Common
Lisp.  @code{save-excursion} is a special form in Emacs Lisp, but
doesn't exist in Common Lisp.  @code{throw} is a special form in
Common Lisp (because it must be able to throw multiple values), but it
is a function in Emacs Lisp (which doesn't have multiple
values).@refill
@end quotation

@node Autoloading,  , Special Forms, Forms
@subsection Autoloading

  The @dfn{autoload} feature allows you to call a function or macro
whose function definition has not yet been loaded into Emacs.  When an
autoload object appears as a symbol's function definition and that
symbol is used as a function, Emacs will automatically install the real
definition (plus other associated code) and then call that definition.
(@xref{Autoload}.)

@node Quoting,  , Forms, Evaluation
@section Quoting
@cindex quoting

  The special form @code{quote} returns its single argument
``unchanged''.

@defspec quote object
This special form returns @var{object}, without evaluating it.  This
allows symbols and lists, which would normally be evaluated, to be
included literally in a program.  (It is not necessary to quote
numbers, strings, and vectors since they are self-evaluating.)  Use
@code{function} instead of @code{quote} when quoting lambda
expressions (@pxref{Anonymous Functions}).

@cindex @samp{'} for quoting
@cindex quoting using apostrophe
@cindex apostrophe for quoting
Because @code{quote} is used so often in programs, a convenient read
syntax is defined for it.  An apostrophe character (@samp{'}) followed
by a Lisp object (in read syntax) expands to a list whose first element
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
(quote (+ 1 2))
     @result{} (+ 1 2)
(quote foo)
     @result{} foo
'foo
     @result{} foo
''foo
     @result{} (quote foo)
'(quote foo)
     @result{} (quote foo)
['foo]
     @result{} [(quote foo)]
@end example
@end defspec

