@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1994, 1998, 2001-2011 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1994, 1998, 2001-2013 Free Software Foundation,
+@c Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/eval
-@node Evaluation, Control Structures, Symbols, Top
+@node Evaluation
@chapter Evaluation
@cindex evaluation
@cindex interpreter
* Intro Eval:: Evaluation in the scheme of things.
* Forms:: How various sorts of objects are evaluated.
* Quoting:: Avoiding evaluation (to put constants in the program).
+* Backquote:: Easier construction of list structure.
* Eval:: How to invoke the Lisp interpreter explicitly.
@end menu
@cindex form
@cindex expression
- A Lisp object that is intended for evaluation is called an
-@dfn{expression} or a @dfn{form}. 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.
+@cindex S-expression
+@cindex sexp
+ A Lisp object that is intended for evaluation is called a @dfn{form}
+or @dfn{expression}@footnote{It is sometimes also referred to as an
+@dfn{S-expression} or @dfn{sexp}, but we generally do not use this
+terminology in this manual.}. 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.
first evaluates the argument (the subform @code{x}). After evaluating
the argument, Emacs @dfn{executes} the function (@code{car}), and if
the function is written in Lisp, execution works by evaluating the
-@dfn{body} of the function. (In this example, however, @code{car} is
-not a Lisp function; it is a primitive function implemented in C.)
+@dfn{body} of the function (in this example, however, @code{car} is
+not a Lisp function; it is a primitive function implemented in C).
@xref{Functions}, for more information about functions and function
calls.
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
-create a new environment for recursive evaluation, by binding
-variables (@pxref{Local Variables}). Such environments are temporary,
-and vanish when the evaluation of the form is complete.
+also temporarily alter the environment by binding variables
+(@pxref{Local Variables}).
@cindex side effect
Evaluating a form may also make changes that persist; these changes
@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, one by
-one, starting with the ``all other types'' which are self-evaluating
-forms.
+ A Lisp object that is intended to be evaluated is called a
+@dfn{form} (or an @dfn{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 ``all other types'' which are self-evaluating forms.
@menu
* Self-Evaluating Forms:: Forms that evaluate to themselves.
@cindex symbol evaluation
When a symbol is evaluated, it is treated as a variable. The result
-is the variable's value, if it has one. If it has none (if its value
-cell is void), an error is signaled. For more information on the use of
-variables, see @ref{Variables}.
+is the variable's value, if it has one. If the symbol has no value as
+a variable, the Lisp interpreter signals an error. For more
+information on the use of variables, see @ref{Variables}.
In the following example, we set the value of a symbol with
@code{setq}. Then we evaluate the symbol, and get back the value that
into the function cell of @code{first}, and the symbol @code{first} into
the function cell of @code{erste}.
-@smallexample
+@example
@group
;; @r{Build this function cell linkage:}
;; ------------- ----- ------- -------
;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
;; ------------- ----- ------- -------
@end group
-@end smallexample
-
-@smallexample
@group
(symbol-function 'car)
@result{} #<subr car>
(erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.}
@result{} 1
@end group
-@end smallexample
+@end example
By contrast, the following example calls a function without any symbol
function indirection, because the first element is an anonymous Lisp
function, not a symbol.
-@smallexample
+@example
@group
((lambda (arg) (erste arg))
'(1 2 3))
@result{} 1
@end group
-@end smallexample
+@end example
@noindent
Executing the function itself evaluates its body; this does involve
symbol function indirection when calling @code{erste}.
+ This form is rarely used and is now deprecated. Instead, you should write it
+as:
+
+@example
+@group
+(funcall (lambda (arg) (erste arg))
+ '(1 2 3))
+@end group
+@end example
+or just
+@example
+@group
+(let ((arg '(1 2 3))) (erste arg))
+@end group
+@end example
+
The built-in function @code{indirect-function} provides an easy way to
perform symbol function indirection explicitly.
Here is how you could define @code{indirect-function} in Lisp:
-@smallexample
+@example
(defun indirect-function (function)
(if (symbolp function)
(indirect-function (symbol-function function))
function))
-@end smallexample
+@end example
@end defun
@node Function Forms
@item defconst
@pxref{Defining Variables}
-@item defmacro
-@pxref{Defining Macros}
-
-@item defun
-@pxref{Defining Functions}
-
@item defvar
@pxref{Defining Variables}
@item save-restriction
@pxref{Narrowing}
-@item save-window-excursion
-@pxref{Window Configurations}
-
@item setq
@pxref{Setting Variables}
@item while
@pxref{Iteration}
-
-@item with-output-to-temp-buffer
-@pxref{Temporary Displays}
@end table
@cindex CL note---special forms compared
@b{Common Lisp note:} Here are some comparisons of special forms in
GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and
@code{catch} are special forms in both Emacs Lisp and Common Lisp.
-@code{defun} is a special form in Emacs Lisp, but a macro in Common
-Lisp. @code{save-excursion} is a special form in Emacs Lisp, but
+@code{save-excursion} is a special form in Emacs Lisp, but
doesn't exist in Common Lisp. @code{throw} is a special form in
Common Lisp (because it must be able to throw multiple values), but it
is a function in Emacs Lisp (which doesn't have multiple
whose function definition has not yet been loaded into Emacs. It
specifies which file contains the definition. When an autoload object
appears as a symbol's function definition, calling that symbol as a
-function automatically loads the specified file; then it calls the real
-definition loaded from that file. @xref{Autoload}.
+function automatically loads the specified file; then it calls the
+real definition loaded from that file. The way to arrange for an
+autoload object to appear as a symbol's function definition is
+described in @ref{Autoload}.
@node Quoting
@section Quoting
to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
only part of a list, while computing and substituting other parts.
+@node Backquote
+@section Backquote
+@cindex backquote (list substitution)
+@cindex ` (list substitution)
+@findex `
+
+ @dfn{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 @code{quote}
+@iftex
+@end iftex
+@ifnottex
+(described in the previous section; @pxref{Quoting}).
+@end ifnottex
+For example, these two forms yield identical results:
+
+@example
+@group
+`(a list of (+ 2 3) elements)
+ @result{} (a list of (+ 2 3) elements)
+@end group
+@group
+'(a list of (+ 2 3) elements)
+ @result{} (a list of (+ 2 3) elements)
+@end group
+@end example
+
+@findex , @r{(with backquote)}
+ The special marker @samp{,} inside of the argument to backquote
+indicates a value that isn't constant. The Emacs Lisp evaluator
+evaluates the argument of @samp{,}, and puts the value in the list
+structure:
+
+@example
+@group
+`(a list of ,(+ 2 3) elements)
+ @result{} (a list of 5 elements)
+@end group
+@end example
+
+@noindent
+Substitution with @samp{,} is allowed at deeper levels of the list
+structure also. For example:
+
+@example
+@group
+`(1 2 (3 ,(+ 4 5)))
+ @result{} (1 2 (3 9))
+@end group
+@end example
+
+@findex ,@@ @r{(with backquote)}
+@cindex splicing (with backquote)
+ You can also @dfn{splice} an evaluated value into the resulting list,
+using the special marker @samp{,@@}. 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 @samp{`} is often unreadable.
+Here are some examples:
+
+@example
+@group
+(setq some-list '(2 3))
+ @result{} (2 3)
+@end group
+@group
+(cons 1 (append some-list '(4) some-list))
+ @result{} (1 2 3 4 2 3)
+@end group
+@group
+`(1 ,@@some-list 4 ,@@some-list)
+ @result{} (1 2 3 4 2 3)
+@end group
+
+@group
+(setq list '(hack foo bar))
+ @result{} (hack foo bar)
+@end group
+@group
+(cons 'use
+ (cons 'the
+ (cons 'words (append (cdr list) '(as elements)))))
+ @result{} (use the words foo bar as elements)
+@end group
+@group
+`(use the words ,@@(cdr list) as elements)
+ @result{} (use the words foo bar as elements)
+@end group
+@end example
+
+
@node Eval
@section Eval
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.
+Often @code{eval} is not needed and something else should be used instead.
+For example, to get the value of a variable, while @code{eval} works,
+@code{symbol-value} is preferable; or rather than store expressions
+in a property list that then need to go through @code{eval}, it is better to
+store functions instead that are then passed to @code{funcall}.
The functions and variables described in this section evaluate forms,
specify limits to the evaluation process, or record recently returned
functions provides the ability to pass information to them as
arguments.
-@defun eval form
-This is the basic function evaluating an expression. It evaluates
+@defun eval form &optional lexical
+This is the basic function for 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}).
+The argument @var{lexical}, if non-@code{nil}, means to evaluate
+@var{form} using lexical scoping rules for variables, instead of the
+default dynamic scoping rules. @xref{Lexical Binding}.
+
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.
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
+@file{*ielm*} buffers, nor evaluation using @kbd{C-j} in
@code{lisp-interaction-mode}.) The elements are ordered most recent
first.