The Lisp interpreter, or evaluator, is the part of Emacs that computes 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 for evaluation is called a form or expression/(It is sometimes also referred to as an /S-expression or sexp). The fact that forms are data objects and not merely text is one of the fundamental differences between Lisp-like languages and typical programming languages. Any object can be evaluated, but in practice only numbers, symbols, lists and strings are evaluated very often. In subsequent sections, we will describe the details of what evaluation means for each kind of form. It is very common to read a Lisp form and then evaluate the form, but reading and evaluation are separate activities, and either can be performed alone. Reading per se does not evaluate anything; it converts the printed representation of a Lisp object to the object itself. It is up to the caller of read to specify whether this object is a form to be evaluated, or serves some entirely different purpose. Input Functions. Evaluation is a recursive process, and evaluating a form often involves evaluating parts within that form. For instance, when you evaluate a function call form such as (car x), Emacs first evaluates the argument (the subform x). After evaluating the argument, Emacs executes the function (car), and if the function is written in Lisp, execution works by evaluating the body of the function (in this example, however, car is not a Lisp function; it is a primitive function implemented in C). Functions, for more information about functions and function calls. Evaluation takes place in a context called the environment, which consists of the current values and bindings of all Lisp variables (Variables).(This definition of "environment" is specifically not intended to include all the data that can affect the result of a program.) Whenever a form refers to a variable without creating a new binding for it, the variable evaluates to the value given by the current environment. Evaluating a form may also temporarily alter the environment by binding variables (Local Variables). Evaluating a form may also make changes that persist; these changes are called side effects. An example of a form that produces a side effect is (setq foo 1). Do not confuse evaluation with command key interpretation. The editor command loop translates keyboard input into a command (an interactively callable function) using the active keymaps, and then uses call-interactively to execute that command. Executing the command usually involves evaluation, if the command is written in Lisp; however, this step is not considered a part of command key interpretation. Command Loop.

A Lisp object that is intended to be evaluated is called a form (or an expression). 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 one, starting with the other types, which are self-evaluating forms.

'123               ; A number
     => 123
123                ; Evaluated as usual---result is the same.
     => 123
(eval '123)        ; Evaluated "by hand"---result is the same.
     => 123
(eval (eval '123)) ; Evaluating twice changes nothing.
     => 123

;; Build an expression containing a buffer object.
(setq print-exp (list 'print (current-buffer)))
     => (print #<buffer eval.texi>)
;; Evaluate it.
(eval print-exp)
     -| #<buffer eval.texi>
     => #<buffer eval.texi>

(setq a 123)
     => 123
(eval 'a)
     => 123
a
     => 123

;; Build this function cell linkage:
;;   -------------       -----        -------        -------
;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
;;   -------------       -----        -------        -------
(symbol-function 'car)
     => #<subr car>
(fset 'first 'car)
     => car
(fset 'erste 'first)
     => first
(erste '(1 2 3))   ; Call the function referenced by erste.
     => 1

((lambda (arg) (erste arg))
 '(1 2 3))
     => 1

(funcall (lambda (arg) (erste arg))
         '(1 2 3))

(let ((arg '(1 2 3))) (erste arg))

(defun indirect-function (function)
  (if (and function
           (symbolp function))
      (indirect-function (symbol-function function))
    function))

(+ 1 x)

(defmacro cadr (x)
  (list 'car (list 'cdr x)))

(car (cdr (assq 'handler list)))

The special form 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.)

quote

This special form returns object, without evaluating it. The returned value might be shared and should not be modified. Self-Evaluating Forms.

Because quote is used so often in programs, Lisp provides a convenient read syntax for it. An apostrophe character (') followed by a Lisp object (in read syntax) expands to a list whose first element is quote, and whose second element is the object. Thus, the read syntax 'x is an abbreviation for (quote x). Here are some examples of expressions that use quote:

(quote (+ 1 2))
     => (+ 1 2)
(quote foo)
     => foo
'foo
     => foo
"foo
     => 'foo
'(quote foo)
     => 'foo
['foo]
     => ['foo]

Although the expressions (list '+ 1 2) and '(+ 1 2) both yield lists equal to (+ 1 2), the former yields a freshly-minted mutable list whereas the latter yields a list built from conses that might be shared and should not be modified. Self-Evaluating Forms. Other quoting constructs include function (Anonymous Functions), which causes an anonymous lambda expression written in Lisp to be compiled, and ` (Backquote), which is used to quote only part of a list, while computing and substituting other parts.

Backquote constructs allow you to quote a list, but selectively evaluate elements of that list. In the simplest case, it is identical to the special form quote (described in the previous section; Quoting). For example, these two forms yield identical results:

`(a list of (+ 2 3) elements)
     => (a list of (+ 2 3) elements)
'(a list of (+ 2 3) elements)
     => (a list of (+ 2 3) elements)

The special marker = inside of the argument to backquote indicates a value that isn't constant. The Emacs Lisp evaluator evaluates the argument of =, and puts the value in the list structure:

`(a list of ,(+ 2 3) elements)
     => (a list of 5 elements)

Substitution with == is allowed at deeper levels of the list structure also. For example:

`(1 2 (3 ,(+ 4 5)))
     => (1 2 (3 9))

You can also splice an evaluated value into the resulting list, using the special marker =. The elements of the spliced list become elements at the same level as the other elements of the resulting list. The equivalent code without using =` is often unreadable. Here are some examples:

(setq some-list '(2 3))
     => (2 3)
(cons 1 (append some-list '(4) some-list))
     => (1 2 3 4 2 3)
`(1 ,@some-list 4 ,@some-list)
     => (1 2 3 4 2 3)

(setq list '(hack foo bar))
     => (hack foo bar)
(cons 'use
  (cons 'the
    (cons 'words (append (cdr list) '(as elements)))))
     => (use the words foo bar as elements)
`(use the words ,@(cdr list) as elements)
     => (use the words foo bar as elements)

A backquote construct acts like quote in that it yields conses, vectors and strings that might be shared and should not be modified. Self-Evaluating Forms.

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. Often eval is not needed and something else should be used instead. For example, to get the value of a variable, while eval works, symbol-value is preferable; or rather than store expressions in a property list that then need to go through eval, it is better to store functions instead that are then passed to funcall. 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 (Loading). It is generally cleaner and more flexible to store a function in a data structure, and call it with funcall or 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.

eval

This is the basic function for evaluating an expression. It evaluates form in the current environment, and returns the result. The type of the form object determines how it is evaluated. Forms. The argument lexical specifies the scoping rule for local variables (Variable Scoping). If it is t, that means to evaluate form using lexical scoping; this is the recommended value. If it is omitted or nil, that means to use the old dynamic-only variable scoping rule. The value of lexical can also be a non-empty list specifying a particular lexical environment for lexical bindings; however, this feature is only useful for specialized purposes, such as in Emacs Lisp debuggers. Each member of the list is either a cons cell which represents a lexical symbol-value pair, or a symbol representing a (special) variable that would use dynamic scoping if bound. 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
;; Here eval receives argument foo
(eval 'foo)
     => bar
;; Here eval receives argument bar
(eval foo)
     => baz

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

Command eval-region

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. By default, eval-region does not produce any output. However, if stream is non-nil, any output produced by output functions (Output Functions), as well as the values that result from evaluating the expressions in the region are printed using stream. Output Streams. If read-function is non-nil, it should be a function, which is used instead of 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 load-read-function (How Programs Do Loading) to specify this function, but it is more robust to use the read-function argument. eval-region does not move point. It always returns nil.

Command eval-buffer

This is similar to eval-region, but the arguments provide different optional features. eval-buffer operates on the entire accessible portion of buffer buffer-or-name (Narrowing). buffer-or-name can be a buffer, a buffer name (a string), or nil (or omitted), which means to use the current buffer. stream is used as in eval-region, unless stream is nil and print non-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. filename is the file name to use for load-history (Unloading), and defaults to buffer-file-name (Buffer File Name). If unibyte is non-nil, read converts strings to unibyte whenever possible.

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 limit, with the associated error when it is exceeded, is how Emacs Lisp avoids infinite recursion on an ill-defined function. If you increase the value of max-lisp-eval-depth too much, such code can cause stack overflow instead. On some systems, this overflow can be handled. In that case, normal Lisp evaluation is interrupted and control is transferred back to the top level command loop (top-level). Note that there is no way to enter Emacs Lisp debugger in this situation. Error Debugging. The depth limit counts internal uses of eval, apply, and 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 1600. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached.

lisp-eval-depth-reserve

In order to be able to debug infinite recursion errors, when invoking the Lisp debugger, Emacs increases temporarily the value of max-lisp-eval-depth, if there is little room left, to make sure the debugger itself has room to execute. The same happens when running the handler of a handler-bind. Handling Errors. The variable lisp-eval-depth-reserve bounds the extra depth that Emacs can add to max-lisp-eval-depth for those exceptional circumstances. The default value of this variable is 200.

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 not include evaluation in *ielm* buffers, nor evaluation using C-j, C-x C-e, and similar evaluation commands in lisp-interaction-mode.) This variable is obsolete, and will be removed in a future version, since it constantly enlarges the memory footprint of the Emacs process. For that reason, we recommend against using it. The elements of values 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 could be 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

Sometimes it is useful to delay the evaluation of an expression, for example if you want to avoid performing a time-consuming calculation if it turns out that the result is not needed in the future of the program. The thunk library provides the following functions and macros to support such deferred evaluation:

thunk-delay

Return a thunk for evaluating the forms. A thunk is a closure (Closures) that inherits the lexical environment of the thunk-delay call. Using this macro requires lexical-binding.

thunk-force

Force thunk to perform the evaluation of the forms specified in the thunk-delay that created the thunk. The result of the evaluation of the last form is returned. The thunk also "remembers" that it has been forced: Any further calls of thunk-force with the same thunk will just return the same result without evaluating the forms again.

thunk-let

This macro is analogous to let but creates "lazy" variable bindings. Any binding has the form (SYMBOL VALUE-FORM). Unlike let, the evaluation of any value-form is deferred until the binding of the according symbol is used for the first time when evaluating the forms. Any value-form is evaluated at most once. Using this macro requires lexical-binding.

Example:

(defun f (number)
  (thunk-let ((derived-number
              (progn (message "Calculating 1 plus 2 times %d" number)
                     (1+ (* 2 number)))))
    (if (> number 10)
        derived-number
      number)))

(f 5)
=> 5

(f 12)
-| Calculating 1 plus 2 times 12
=> 25

Because of the special nature of lazily bound variables, it is an error to set them (e.g. with setq).

thunk-let*

This is like thunk-let but any expression in bindings is allowed to refer to preceding bindings in this thunk-let* form. Using this macro requires lexical-binding.

(thunk-let* ((x (prog2 (message "Calculating x...")
                    (+ 1 1)
                  (message "Finished calculating x")))
             (y (prog2 (message "Calculating y...")
                    (+ x 1)
                  (message "Finished calculating y")))
             (z (prog2 (message "Calculating z...")
                    (+ y 1)
                  (message "Finished calculating z")))
             (a (prog2 (message "Calculating a...")
                    (+ z 1)
                  (message "Finished calculating a"))))
  (* z x))

-| Calculating z...
-| Calculating y...
-| Calculating x...
-| Finished calculating x
-| Finished calculating y
-| Finished calculating z
=> 8

thunk-let and thunk-let* use thunks implicitly: their expansion creates helper symbols and binds them to thunks wrapping the binding expressions. All references to the original variables in the body forms are then replaced by an expression that calls thunk-force with the according helper variable as the argument. So, any code using thunk-let or thunk-let* could be rewritten to use thunks, but in many cases using these macros results in nicer code than using thunks explicitly.