@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, 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
@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.
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, one by
+and ``all other types.'' This section describes all three kinds, one by
one, starting with the ``all other types'' which are self-evaluating
forms.
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.
@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
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
@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.
-If @var{stream} is non-@code{nil}, 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{How Programs
-Do Loading}) to specify this function, but it is more robust to use the
+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} always returns @code{nil}.
+@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
HCoop / bpt / emacs.git / blobdiff