@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2001, 2002, 2003,
+@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/eval
@node Evaluation, Control Structures, Symbols, Top
your program, but can also be called explicitly via the Lisp primitive
function @code{eval}.
-@ifinfo
+@ifnottex
@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).
+* 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 computes
-the value of an expression that is given to it. When a function
+the value of an expression that 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
+@end ifnottex
@cindex forms
@cindex expression
@dfn{environment}, which consists of the current values and bindings of
all Lisp variables.@footnote{This definition of ``environment'' is
specifically not intended to include all the data that can affect the
-result of a program.} Whenever the form refers to a variable without
-creating a new binding for it, the value of the binding in the current
-environment is used. @xref{Variables}.
+result of a program.} Whenever a form refers to a variable without
+creating a new binding for it, the value of the variable's binding in
+the current environment is used. @xref{Variables}.
@cindex side effect
Evaluation of a form may create new environments for recursive
The details of what evaluation means for each kind of form are
described below (@pxref{Forms}).
-@node Eval
-@section Eval
-@c ??? Perhaps this should be the last section in the chapter.
-
- 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
-after reading a form from text being edited or getting one from a
-property list. On these occasions, use the @code{eval} function.
-
- @strong{Note:} it is generally cleaner and more flexible to call
-functions that are stored in data structures, rather than to evaluate
-expressions stored in data structures. Using functions provides the
-ability to pass information to them as arguments.
-
- The functions and variables described in this section evaluate forms,
-specify limits to the evaluation process, or record recently returned
-values. Loading a file also does evaluation (@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
-@group
-(setq foo 'bar)
- @result{} bar
-@end group
-@group
-(setq bar 'baz)
- @result{} baz
-;; @r{@code{eval} receives argument @code{bar}, which is the value of @code{foo}}
-(eval foo)
- @result{} baz
-(eval 'foo)
- @result{} bar
-@end group
-@end example
-
-The 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
-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
-during the evaluation.
-
-You can use the variable @code{load-read-function} to specify a function
-for @code{eval-region} to use instead of @code{read} for reading
-expressions. @xref{How Programs Do Loading}.
-
-@code{eval-region} always returns @code{nil}.
-@end deffn
-
-@cindex evaluation of buffer contents
-@deffn Command eval-current-buffer &optional stream
-This is like @code{eval-region} except that it operates on the whole
-buffer.
-@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"}). This counts
-internal uses of those functions, such as for calling the functions
-mentioned in Lisp expressions, and recursive evaluation of function call
-arguments and function body forms.
-
-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.
-
-@code{max-specpdl-size} provides another limit on nesting.
-@xref{Local Variables}.
-@end defvar
-
-@defvar values
-The value of this variable is a list of the values returned by all the
-expressions that were read from buffers (including the minibuffer),
-evaluated, and printed. 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
-@group
-values
- @result{} ((A 3 t) 1 @dots{})
-@end group
-@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
-@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
-
@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 three
different kinds of form that are evaluated differently: symbols, lists,
-and ``all other types''. This section describes all three kinds,
-starting with ``all other types'' which are self-evaluating forms.
+and ``all other types.'' This section describes all three kinds, one by
+one, starting with the ``all other types'' which are self-evaluating
+forms.
@menu
* Self-Evaluating Forms:: Forms that evaluate to themselves.
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,
+* Special Forms:: "Special forms" are idiosyncratic primitives,
most of them extremely important.
* Autoloading:: Functions set up to load files
containing their real definitions.
@example
@group
-'123 ; @r{An object, shown without evaluation.}
+'123 ; @r{A number, shown without evaluation.}
@result{} 123
@end group
@group
@example
@group
;; @r{Build an expression containing a buffer object.}
-(setq buffer (list 'print (current-buffer)))
+(setq print-exp (list 'print (current-buffer)))
@result{} (print #<buffer eval.texi>)
@end group
@group
;; @r{Evaluate it.}
-(eval buffer)
+(eval print-exp)
@print{} #<buffer eval.texi>
@result{} #<buffer eval.texi>
@end group
value of @code{nil} is always @code{nil}, and the value of @code{t} is
always @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.
+@code{eval} treats them like any other symbol. A symbol whose name
+starts 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
@smallexample
@group
((lambda (arg) (erste arg))
- '(1 2 3))
+ '(1 2 3))
@result{} 1
@end group
@end smallexample
perform symbol function indirection explicitly.
@c Emacs 19 feature
-@defun indirect-function function
+@defun indirect-function function &optional noerror
+@anchor{Definition of indirect-function}
This function returns the meaning of @var{function} as a function. If
@var{function} is a symbol, then it finds @var{function}'s function
definition and starts over with that value. If @var{function} is not a
symbol, then it returns @var{function} itself.
+This function signals a @code{void-function} error if the final symbol
+is unbound and optional argument @var{noerror} is @code{nil} or
+omitted. Otherwise, if @var{noerror} is non-@code{nil}, it returns
+@code{nil} if the final symbol is unbound.
+
+It signals a @code{cyclic-function-indirection} error if there is a
+loop in the chain of symbols.
+
Here is how you could define @code{indirect-function} in Lisp:
@smallexample
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 computed when the expansion is computed.
+expansion, so they are computed when the expansion is evaluated.
For example, given a macro defined as follows:
@item quote
@pxref{Quoting}
+@item save-current-buffer
+@pxref{Current Buffer}
+
@item save-excursion
@pxref{Excursions}
Functions}), which causes an anonymous lambda expression written in Lisp
to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
only part of a list, while computing and substituting other parts.
+
+@node Eval
+@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
+after reading a form from text being edited or getting one from 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. Loading a file also does evaluation (@pxref{Loading}).
+
+ It is generally cleaner and more flexible to store a function in a
+data structure, and call it with @code{funcall} or @code{apply}, than
+to store an expression in the data structure and evaluate it. Using
+functions provides the ability to pass information to them as
+arguments.
+
+@defun eval form
+This is the basic function evaluating an expression. 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
+@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 example
+
+The 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-function
+@anchor{Definition of eval-region}
+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.
+
+By default, @code{eval-region} does not produce any output. However,
+if @var{stream} is non-@code{nil}, any output produced by output
+functions (@pxref{Output Functions}), as well as the values that
+result from evaluating 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,
+which is used instead of @code{read} to read expressions one by one.
+This function is called with one argument, the stream for reading
+input. You can also use the variable @code{load-read-function}
+(@pxref{Definition of load-read-function,, How Programs Do Loading})
+to specify this function, but it is more robust to use the
+@var{read-function} argument.
+
+@code{eval-region} does not move point. It always returns @code{nil}.
+@end deffn
+
+@cindex evaluation of buffer contents
+@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
+This is similar to @code{eval-region}, but the arguments provide
+different optional features. @code{eval-buffer} operates on the
+entire accessible portion of buffer @var{buffer-or-name}.
+@var{buffer-or-name} can be a buffer, a buffer name (a string), or
+@code{nil} (or omitted), which means to use the current buffer.
+@var{stream} is used as in @code{eval-region}, unless @var{stream} is
+@code{nil} and @var{print} non-@code{nil}. In that case, values that
+result from evaluating the expressions are still discarded, but the
+output of the output functions is printed in the echo area.
+@var{filename} is the file name to use for @code{load-history}
+(@pxref{Unloading}), and defaults to @code{buffer-file-name}
+(@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil},
+@code{read} converts strings to unibyte whenever possible.
+
+@findex eval-current-buffer
+@code{eval-current-buffer} is an alias for this command.
+@end deffn
+
+@defvar max-lisp-eval-depth
+@anchor{Definition of 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"}).
+
+This limit, with the associated error when it is exceeded, is one way
+Emacs Lisp avoids infinite recursion on an ill-defined function. If
+you increase the value of @code{max-lisp-eval-depth} too much, such
+code can cause stack overflow instead.
+@cindex Lisp nesting error
+
+The depth limit counts internal uses of @code{eval}, @code{apply}, and
+@code{funcall}, such as for calling the functions mentioned in Lisp
+expressions, and recursive evaluation of function call arguments and
+function body forms, as well as explicit calls in Lisp code.
+
+The default value of this variable is 300. If you set it to a value
+less 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 room
+left, to make sure the debugger itself has room to execute.
+
+@code{max-specpdl-size} provides another limit on nesting.
+@xref{Definition of max-specpdl-size,, Local Variables}.
+@end defvar
+
+@defvar values
+The value of this variable is a list of the values returned by all the
+expressions that were read, evaluated, and printed from buffers
+(including the minibuffer) by the standard Emacs commands which do
+this. (Note that this does @emph{not} include evaluation in
+@samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in
+@code{lisp-interaction-mode}.) 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
+@group
+values
+ @result{} ((A 3 t) 1 @dots{})
+@end group
+@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
+@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
+
+@ignore
+ arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57
+@end ignore