+
+@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