@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, 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.
-* 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
recursively, so that its value can be passed as an argument to the
function @code{car}.
+ Evaluation of a function call ultimately calls the function specified
+in it. @xref{Functions}. The execution of the function may itself work
+by evaluating the function definition; or the function may be a Lisp
+primitive implemented in C, or it may be a byte-compiled function
+(@pxref{Byte Compilation}).
+
@cindex environment
The evaluation of forms takes place in a context called the
@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
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 may on occasion invoke
-the Lisp interpreter. (@xref{Byte Compilation}.)
-
The details of what evaluation means for each kind of form are
described below (@pxref{Forms}).
-@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}).
-
-@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
-
-@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 until 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 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
-
-@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.
@example
@group
-'123 ; @r{An object, shown without evaluation.}
+'123 ; @r{A number, shown without evaluation.}
@result{} 123
@end group
@group
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 there's no way to write them textually; however, it is
-possible to construct Lisp expressions containing these types by means
-of a Lisp program. Here is an example:
+syntax, because there's no way to write them textually. It is possible
+to construct Lisp expressions containing these types by means of a Lisp
+program. Here is an example:
@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
@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
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}
@section Quoting
@cindex quoting
- The special form @code{quote} returns its single argument
-``unchanged''.
+ The special form @code{quote} returns its single argument, as written,
+without evaluating it. This provides a way to include constant symbols
+and lists, which are not self-evaluating objects, in a program. (It is
+not necessary to quote self-evaluating objects such as numbers, strings,
+and vectors.)
@defspec quote object
-This special form returns @var{object}, without evaluating it. This
-provides a way to include constant symbols and lists, which are not
-self-evaluating objects, in a program. (It is not necessary to quote
-self-evaluating objects such as numbers, strings, and vectors.)
+This special form returns @var{object}, without evaluating it.
+@end defspec
@cindex @samp{'} for quoting
@cindex quoting using apostrophe
@result{} [(quote foo)]
@end group
@end example
-@end defspec
Other quoting constructs include @code{function} (@pxref{Anonymous
Functions}), which causes an anonymous lambda expression written in Lisp
-to be compiled, and @code{`} (@pxref{Backquote}), which is used to quote
+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