@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 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2003, 2004 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.
* Forms:: How various sorts of objects are evaluated.
@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
@smallexample
@group
((lambda (arg) (erste arg))
- '(1 2 3))
+ '(1 2 3))
@result{} 1
@end group
@end smallexample
@c Emacs 19 feature
@defun indirect-function function
+@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 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
specify limits to the evaluation process, or record recently returned
values. Loading a file also does evaluation (@pxref{Loading}).
- @strong{Note:} 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.
+ 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
@code{max-lisp-eval-depth} (see below).
@end defun
-@deffn Command eval-region start end &optional stream
+@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.
-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}.
+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-current-buffer &optional stream
-This is like @code{eval-region} except that it operates on the whole
-buffer.
+@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 that Lisp
-avoids infinite recursion on an ill-defined function.
+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
left, to make sure the debugger itself has room to execute.
@code{max-specpdl-size} provides another limit on nesting.
-@xref{Local Variables}.
+@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.
-The elements are ordered most recent first.
+(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
@end group
@end example
@end defvar
+
+@ignore
+ arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57
+@end ignore