⟦3fa97f164⟧

TextFile

@setfilename ../info/eval
@node Evaluation, Loading, Control Structures, Top
@chapter Evaluation

  The @dfn{evaluation} of objects in Emacs Lisp invokes the @dfn{Lisp
interpreter}.  The Lisp interpreter, which is actually the @code{eval}
function described below, looks at the object it is given, and computes
its @dfn{value as an expression} in a fashion depending on the object's
type.

@ifinfo
@menu
* Intro Eval::  Evaluation in the scheme of things.
* Eval::        The Lisp interpreter.
* Forms::       The objects to be evaluated.
* Quoting::     Avoiding evaluation.
@end menu

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

  The @dfn{evaluation} of objects in Emacs Lisp invokes the @dfn{Lisp
interpreter}.  The Lisp interpreter, which is actually the @code{eval}
function described below, looks at the object it is given, and returns
its @dfn{value as an expression} in a fashion depending on the object's
type.
@end ifinfo

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

  First, evaluation is not command key interpretation.  The editing
command loop interprets keyboard input using the current keymaps, and
then uses @code{call-interactively} to invoke the command.  The
execution of the command itself usually involves evaluation, but that
is another matter.  (@xref{Command Loop}.)

  Second, evaluation does not result from simply reading a form.
Reading produces the form itself, not the value of the form.  It
converts the printed representation of the form to a Lisp object, which
@emph{is} the form in the strict sense.

@cindex recursive evaluation
  Evaluation is a recursive process.  That is, evaluation of a form may
cause @code{eval} to be called again to evaluate parts of the form.  For
example, evaluation of a function call first causes evaluation of each
argument of the function call, and then evaluation of each form in the
function.  Consider the form @code{(car x)}: the subform @code{x} is
first evaluated recursively, so that its value can be passed as an
argument to the function @code{car}.

@cindex evaluation of forms
  The evaluation of forms takes place in a context called the
@dfn{environment}.  This consists of the ambient, inherited 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
ambient binding is used.  (@xref{Variables}.)

  Evaluation of a form may create new environments for nested, 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 it may invoke the Lisp
interpreter.  (@xref{Byte Compilation}.)

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

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

  Most forms, most of the time, are evaluated automatically, by virtue
of their occurence in a program.  But on rare occasions, you may need
to write code that evaluates a form; for example, if the form is
found in a file being edited.  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 calling @code{apply}
and @code{funcall} (@pxref{Calling Functions}) and @code{load}
(@pxref{Loading}).  The details of what evaluation means for each kind
of form are described in another section; @pxref{Forms}.

@defun eval form
  This is the basic function that performs 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 you write
for it 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 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 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 an error is signaled and not handled.

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

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

@defvar max-specpdl-size
@cindex unwind-protect error
@cindex variable limit error
@cindex evaluation error
@cindex infinite recursion
  This variable defines the limit on the number of local variable bindings
and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits}) that are
allowed before the error @code{error} is signaled (with data
@code{"Variable binding depth exceeds max-specpdl-size"}).

  This limit and the associated error when it is exceeded is one way
that Lisp avoids infinite recursion on an ill-defined function.

  The default value is 600.
@end defvar

@defvar max-lisp-eval-depth
  This variable defines the maximum depth allowed in calls to @code{eval},
@code{apply}, and @code{funcall} before the error @code{error} is
signaled (with data @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 and 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 is 200.  If you set it to a value less than 100, Lisp
will reset it to 100.
@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 you have
evaluated.  It is generally a bad idea to examine the value of
@code{values} directly, since it 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)
(nth 3 values)
     @result{} 1
@end example
@end defvar

@node Forms, Quoting, Eval, Evaluation
@section Kinds of Forms

  Any Lisp object that we intend to evaluate is 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
* Nonempty List Forms::         Function and macro calls, and special forms
@end menu

@node Self-Evaluating Forms, Symbol Forms, Forms, Forms
@subsection Self-Evaluating Forms

@cindex vector evaluation
@cindex literal evaluation
  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 that very vector.

@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 useful; but it is possible
to put them inside Lisp programs when they are constructed @emph{as
Lisp objects}.  Here is an example:

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

@node Symbol Forms, Nonempty List Forms, 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), you get an error.  For more information on the binding
of variables, @pxref{Variables}.

  In the following example, the value cell of a symbol is set to a
value (with @code{setq}).  When the symbol is then evaluated, that
value is returned.

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

  Two symbols, @code{nil} and @code{t}, are special, because 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 Nonempty List Forms,  , Symbol Forms, Forms
@subsection Nonempty List Forms

@cindex list form evaluation
  A form which 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.

@menu
* Classifying Lists::	
* Function Forms::
* Macro Forms::
* Special Forms::
* Autoloading::
@end menu

@node Classifying Lists, Function Forms, Nonempty List Forms, Nonempty List Forms
@subsection Classification of List Forms

  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 dialects of Lisp
languages, such as Scheme.

@cindex dereferencing indirection
@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.  If the object
referenced by the function cell is another symbol, the function cell
of that symbol is examined, and used exactly as if it had been the
original symbol.  If that is 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, if 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 a function or a related 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.

@cindex symbol indirection
@cindex indirection for symbols
  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}).  In this way 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
@findex fset @r{example}
(symbol-function 'car)
     @result{} #<subr car>
(fset 'first 'car)
     @result{} car
(fset 'erste 'first)
     @result{} first
(erste '(1 2 3))           ; @r{Call the function referenced by @code{erste}.}
     @result{} 1
@end example

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

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

@noindent
However, 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, Nonempty List Forms
@subsection Evaluation of Function Forms

@cindex function evaluation
  If the first element of a list being evaluated is a Lisp function
object or primitive function object, then that form is called a
@dfn{function call}.  For example, this is a call to the function
@code{+}:

@example
(+ 1 x)
@end example

  When a function call is evaluated, first the elements of the rest of
the list are evaluated in the order they appear.  Then the function is
called with this list of arguments, effectively using the function
@code{apply} to do this (@pxref{Calling Functions}).  If the function is
written in Lisp, the arguments are used to bind the parameter 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, Nonempty List Forms
@subsection Lisp Macro Evaluation

@cindex macro evaluation
  If the first element of a list being evaluated is a macro object,
then that form is called 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.  Then the
expansion 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, as usual.

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

@node Special Forms, Autoloading, Macro Forms, Nonempty List 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.  Sometimes, whether a
particular argument is evaluated depends 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 defvar
@pxref{Global Variables}

@item defmacro
@pxref{Defining Macros}

@item defun
@pxref{Defining Functions}

@item defvar
@pxref{Defining Variables}

@item if
@pxref{Conditionals}

@item function
@pxref{Anonymous Functions}

@item interactive
@pxref{Interactive Call}

@item let
@pxref{Local Variables}

@item let*
@pxref{Local Variables}

@item or
@pxref{Combining Conditions}

@item progn
@pxref{Sequencing}

@item prog1
@pxref{Sequencing}

@item prog2
@pxref{Sequencing}

@item quote
@pxref{Quoting}

@item save-excursion
@pxref{Excursions}

@item save-restriction
@pxref{Clipping Restrictions}

@item save-window-excursion
@pxref{Window Configurations}

@item setq
@pxref{Setting Variables}

@item setq-default
@pxref{Buffer Local Variables}

@item unwind-protect
@pxref{Nonlocal Exits}

@item while
@pxref{Iteration}

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

@quotation
@cindex Common Lisp special forms
@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, Nonempty List 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 and its 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 quote using apostrophe
@cindex apostrophe for quote
Because @code{quote} is used so often in programs, a convenient read
syntax is defined.  An apostrophe character (@samp{'}) followed
by a form expands to a list whose first element is
@code{quote}, and whose second element is the form.

@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
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦3fa97f164⟧ TextFile

Derivation

TextFile
