A program is a sequence of forms. The Lisp reader turns text into objects, and the evaluator treats each object as a form and computes its value. Evaluation is the whole of the language’s semantics: there is no separate statement syntax. This page lists the kinds of form, the order in which things happen, the special forms that the evaluator itself knows, and the functions that start evaluation from a program.
Kinds of form
| The object is | Value |
|---|---|
| a number, string, vector, bool-vector, char-table, record, or other non-symbol, non-cons object | itself (self-evaluating); a vector is not searched for forms |
nil, t, a keyword | itself |
| any other symbol | its variable value: the lexical binding if there is one in scope, otherwise the dynamic value; an unbound symbol signals void-variable |
| a list whose first element is a special form name | whatever that special form computes from its unevaluated arguments |
| a list whose first element names a macro | the macro is expanded, then the expansion is evaluated |
| a list whose first element names a function | the arguments are evaluated left to right, then the function is called with the values |
a list whose first element is a lambda expression, (lambda …) | the same as a call to an anonymous function |
| a list whose first element is anything else | signals invalid-function, and a dotted list signals wrong-type-argument |
When the head of a list is a symbol, the evaluator follows its function cell, through any number of aliases, until it reaches a function, a macro or a special form. A void function cell signals void-function. An autoload object in the cell is loaded first (Packages and autoloads).
Order of evaluation
- The function position is resolved; it is not evaluated as a variable.
(foo 1)never reads the value offoo. - For a function call, the arguments are evaluated from left to right, then the function is called. All arguments are evaluated even if the function ignores them.
- For a macro call, the arguments are not evaluated. The macro function receives the argument forms, returns a new form, and that form is evaluated in the place of the call (Macros).
- For a special form, the evaluator runs the special form’s own rule, and may evaluate some arguments, all of them in order, or none.
The result of evaluating a list is the value returned by the call; the value of a sequence of forms is the value of the last. Side effects happen in the order given. Because arguments are evaluated before the call, an expression like (list (setq a 1) a) sees the new value of a in its second element.
Quoting
| Syntax | Reads as | Meaning |
|---|---|---|
'X | (quote X) | returns X unevaluated, as a constant |
#'X | (function X) | for a symbol, returns the symbol and marks it as a function name for the compiler; for a lambda expression, makes a closure over the current lexical environment under lexical-binding, and lets the byte compiler compile it |
`X | (\` X) | backquote, a template (below) |
,X and ,@X | (\, X) and (\,@ X) | unquote and splice, valid only inside a backquote |
A bare (lambda (x) x) is a macro that expands to (function (lambda (x) x)), so writing #' before a lambda is optional. A quoted lambda, '(lambda (x) x), is a plain list and does not capture variables.
The special forms
Special forms are the primitives that cannot be functions, because they do not evaluate their arguments in the usual way. Everything else is built on them. special-form-p tests a symbol. The list in Emacs’s manual is the following.
| Special form | What it does |
|---|---|
and, or | short-circuit conjunction and disjunction; return the last value computed |
catch | sets up a tag that throw can jump to |
cond | multi-way conditional, a list of clauses |
condition-case | handles errors raised in its body |
defconst | defines a constant variable and marks it special |
defvar | defines a variable once, without overwriting a value, and marks it special (dynamically bound) |
function | quotes a function, makes closures |
if | conditional with an implicit progn in the else part only |
interactive | marks a function as a command; does nothing when evaluated |
let, let* | bind variables for a body, in parallel or in sequence |
prog1, prog2, progn | sequence forms and choose which value to return |
quote | returns its argument unevaluated |
save-current-buffer | restores the current buffer on exit |
save-excursion | restores the current buffer and point on exit |
save-restriction | restores the narrowing on exit |
setq | sets one or more variables, pairwise, left to right |
setq-default | sets default values of buffer-local variables |
unwind-protect | runs cleanup forms whether the body exits normally or not |
while | loops while its test is non-nil |
handler-bind | runs handler functions at the point of an error, without unwinding; new in Emacs 30 |
Some names that look like special forms are macros in current Emacs, for example prog2, when and unless; use special-form-p and macrop on a symbol if the difference matters. The forms are described in Control structures and Variables and scope.
Starting evaluation from a program
| Function | Meaning |
|---|---|
(eval FORM &optional LEXICAL) | evaluates FORM. LEXICAL is t for lexical binding (the recommended value), a non-empty alist that serves as the starting lexical environment, or nil or omitted for the old dynamic-only scoping |
(funcall FUNCTION &rest ARGS) | calls FUNCTION with ARGS, which are already evaluated |
(apply FUNCTION &rest ARGS) | like funcall, but the last argument is a list whose elements become the remaining arguments; (apply #'+ 1 2 '(3 4)) is 10; with one argument that is a list, the first element is the function |
(apply-partially FUNCTION &rest ARGS) | returns a function that calls FUNCTION with ARGS followed by its own arguments |
(identity X), (ignore &rest ARGS) | return X; return nil |
(eval-buffer), (eval-region START END), (eval-expression FORM), (load FILE) | read and evaluate forms from text; lexical or dynamic binding is chosen by the lexical-binding variable, which the file cookie sets |
(read-from-string STRING), (read STREAM) | turn text into a form, without evaluating it |
(eval-when-compile BODY…), (eval-and-compile BODY…) | compile-time evaluation; see Byte-compilation |
(eval '(* 2 3) t) ; => 6
(funcall #'+ 1 2) ; => 3
(apply #'max '(3 9 4)) ; => 9
(funcall (apply-partially #'+ 10) 5) ; => 15The function position of funcall is a value, so a variable that holds a function works there, as in (funcall fn x). In the call (fn x) the symbol fn would be looked up as a function, not a variable.
Backquote evaluation
A backquoted form is a template. Everything in it is quoted except the parts marked by a comma. ,FORM evaluates FORM and puts the value in that place. ,@FORM evaluates FORM to a list and splices its elements into the surrounding list; it is allowed only inside a list, and not at the very end of a dotted list. Backquote works inside vectors as well. The backquote macro expands into calls to list, cons, append and vconcat.
(let ((x 3) (xs '(a b)))
`(x ,x ,@xs end)) ; => (x 3 a b end)
`[1 ,(+ 1 1)] ; => [1 2]Nested backquotes are covered in Macros.
Lexical and dynamic evaluation
The variable lexical-binding is read by the evaluator when a form is read from a buffer or file; it is set by the file’s first-line cookie (File structure). With lexical binding, let and function parameters create bindings that only code in the same form can see, and a lambda keeps the bindings it uses. A variable declared special by defvar is bound dynamically even then. The second argument of eval chooses the mode for that call. Details are in Variables and scope.
Evaluation depth
Nested evaluation and function calls are limited so that runaway recursion does not exhaust the C stack. The user option max-lisp-eval-depth sets the limit on nested calls to eval, apply and funcall, including the internal uses that call functions such as hooks. When the depth is exceeded, Emacs signals an error whose message says that Lisp nesting exceeds max-lisp-eval-depth. Raising the value too far can turn the error into a real stack overflow. Emacs 30 adds lisp-eval-depth-reserve, which bounds how far Emacs may temporarily raise the limit so that a handler can run after the error. A deep recursion that is not infinite should be rewritten as a loop; Emacs Lisp does not do tail-call optimisation.
The related variable max-specpdl-size bounded the number of variable bindings in older versions. It is obsolete since Emacs 29, where max-lisp-eval-depth alone limits recursion and stack use.
Macro expansion
| Function | Meaning |
|---|---|
(macroexpand FORM &optional ENV) | expands the form at the top, repeatedly, until its head is no longer a macro; sub-forms are left alone |
(macroexpand-1 FORM &optional ENV) | expands one step only |
(macroexpand-all FORM &optional ENV) | expands every macro in the form and its sub-forms, understanding the special forms |
macroexpand-all-environment, ENV | an alist of (NAME . EXPANDER) for local macros, as made by macroexpand-all for cl-macrolet |
Eager macro expansion runs macroexpand-all over a form before it is evaluated, when loading a file. The byte compiler expands macros before compiling. eval-when-compile and eval-and-compile are described in Byte-compilation.
Not described
Known, not yet covered
- Reference: the default value of
max-lisp-eval-depthin each Emacs version, the exact error symbol signalled when it is exceeded, and the internal counterlisp-eval-depthare not given. - Reference: which of the names in the special-forms table are still primitives in the C sources of the current Emacs, and which became macros, is not checked one by one.
- Reference:
eval-bufferandloadoptions (load-source-file-function,load-read-function) and the eager macro-expansion hook are not tabulated; see Packages and autoloads.
See also
- Control structures – the conditionals, loops and error handling that sit on the special forms
- Macros – how macro calls are defined and expanded
- Functions – lambda, closures and calling conventions
- Evaluation – the manual’s chapter
- Special Forms – the manual’s list of special forms