@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, 2002, 2003, 2004,
+@c 2005, 2006 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
@example
@group
-'123 ; @r{An object, shown without evaluation.}
+'123 ; @r{A number, shown without evaluation.}
@result{} 123
@end group
@group
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. A symbol whose name
-starts with @samp{:} also self-evaluates in the same way.
+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
@item quote
@pxref{Quoting}
+@item save-current-buffer
+@pxref{Current Buffer}
+
@item save-excursion
@pxref{Excursions}
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 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.
+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.
+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 default value of this variable is 200. If you set it to a value
+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{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