14.2 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 eval function.

Please note: it is generally cleaner and more flexible to call functions that are stored in data structures, rather than to evaluate expressions stored in data structures. Using functions provides the ability to pass information to them as arguments.

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 (see Loading).

Function: eval form

This is the basic function for performing evaluation. It evaluates form in the current environment and returns the result. How the evaluation proceeds depends on the type of the object (see Forms).

Since eval is a function, the argument expression that appears in a call to eval is evaluated twice: once as preparation before eval is called, and again by the eval function itself. Here is an example:

(setq foo 'bar)
     ⇒ bar

(setq bar 'baz)
     ⇒ baz
;; eval receives argument bar, which is the value of foo
(eval foo)
     ⇒ baz
(eval 'foo)
     ⇒ bar

The number of currently active calls to eval is limited to max-lisp-eval-depth (see below).

Command: eval-region start end &optional stream

This function evaluates the forms in the current buffer in the region defined by the positions start and end. It reads forms from the region and calls eval on them until the end of the region is reached, or until an error is signaled and not handled.

If stream is supplied, standard-output is bound to it during the evaluation.

You can use the variable load-read-function to specify a function for eval-region to use instead of read for reading expressions. See How Programs Do Loading.

eval-region always returns nil.

Command: eval-buffer buffer &optional stream

This is like eval-region except that it operates on the whole contents of buffer.

Variable: max-lisp-eval-depth

This variable defines the maximum depth allowed in calls to eval, apply, and funcall before an error is signaled (with error message "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.

The default value of this variable is 1000. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached.

max-specpdl-size provides another limit on nesting. See Local Variables.

Variable: 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.

(setq x 1)
     ⇒ 1

(list 'A (1+ 2) auto-save-default)
     ⇒ (A 3 t)

values
     ⇒ ((A 3 t) 1 …)

This variable is useful for referring back to values of forms recently evaluated. It is generally a bad idea to print the value of values itself, since this may be very long. Instead, examine particular elements, like this:

;; Refer to the most recent evaluation result.
(nth 0 values)
     ⇒ (A 3 t)

;; That put a new element on,
;;   so all elements move back one.
(nth 1 values)
     ⇒ (A 3 t)

;; This gets the element that was next-to-most-recent
;;   before this example.
(nth 3 values)
     ⇒ 1