Mercurial > emacs
annotate doc/lispref/eval.texi @ 106508:8c836ea59444
* net/tramp.el (tramp-handle-insert-directory): Suppress error messages.
author | Michael Albinus <michael.albinus@gmx.de> |
---|---|
date | Wed, 09 Dec 2009 10:23:00 +0000 |
parents | c32ec20d0ab5 |
children | 1d1d5d9bd884 |
rev | line source |
---|---|
84066 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2001, 2002, 2003, | |
100974 | 4 @c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. |
84066 | 5 @c See the file elisp.texi for copying conditions. |
84116
0ba80d073e27
(setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents:
84066
diff
changeset
|
6 @setfilename ../../info/eval |
84066 | 7 @node Evaluation, Control Structures, Symbols, Top |
8 @chapter Evaluation | |
9 @cindex evaluation | |
10 @cindex interpreter | |
11 @cindex interpreter | |
12 @cindex value of expression | |
13 | |
14 The @dfn{evaluation} of expressions in Emacs Lisp is performed by the | |
15 @dfn{Lisp interpreter}---a program that receives a Lisp object as input | |
16 and computes its @dfn{value as an expression}. How it does this depends | |
17 on the data type of the object, according to rules described in this | |
18 chapter. The interpreter runs automatically to evaluate portions of | |
19 your program, but can also be called explicitly via the Lisp primitive | |
20 function @code{eval}. | |
21 | |
22 @ifnottex | |
23 @menu | |
24 * Intro Eval:: Evaluation in the scheme of things. | |
25 * Forms:: How various sorts of objects are evaluated. | |
26 * Quoting:: Avoiding evaluation (to put constants in the program). | |
27 * Eval:: How to invoke the Lisp interpreter explicitly. | |
28 @end menu | |
29 | |
30 @node Intro Eval | |
31 @section Introduction to Evaluation | |
32 | |
102222
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
33 The Lisp interpreter, or evaluator, is the part of Emacs that |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
34 computes the value of an expression that is given to it. When a |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
35 function written in Lisp is called, the evaluator computes the value |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
36 of the function by evaluating the expressions in the function body. |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
37 Thus, running any Lisp program really means running the Lisp |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
38 interpreter. |
84066 | 39 @end ifnottex |
40 | |
102222
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
41 @cindex form |
84066 | 42 @cindex expression |
43 A Lisp object that is intended for evaluation is called an | |
102222
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
44 @dfn{expression} or a @dfn{form}. The fact that forms are data |
84066 | 45 objects and not merely text is one of the fundamental differences |
46 between Lisp-like languages and typical programming languages. Any | |
47 object can be evaluated, but in practice only numbers, symbols, lists | |
48 and strings are evaluated very often. | |
49 | |
102222
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
50 In subsequent sections, we will describe the details of what |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
51 evaluation means for each kind of form. |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
52 |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
53 It is very common to read a Lisp form and then evaluate the form, |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
54 but reading and evaluation are separate activities, and either can be |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
55 performed alone. Reading per se does not evaluate anything; it |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
56 converts the printed representation of a Lisp object to the object |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
57 itself. It is up to the caller of @code{read} to specify whether this |
84066 | 58 object is a form to be evaluated, or serves some entirely different |
59 purpose. @xref{Input Functions}. | |
60 | |
102222
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
61 @cindex recursive evaluation |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
62 Evaluation is a recursive process, and evaluating a form often |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
63 involves evaluating parts within that form. For instance, when you |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
64 evaluate a @dfn{function call} form such as @code{(car x)}, Emacs |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
65 first evaluates the argument (the subform @code{x}). After evaluating |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
66 the argument, Emacs @dfn{executes} the function (@code{car}), and if |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
67 the function is written in Lisp, execution works by evaluating the |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
68 @dfn{body} of the function. (In this example, however, @code{car} is |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
69 not a Lisp function; it is a primitive function implemented in C.) |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
70 @xref{Functions}, for more information about functions and function |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
71 calls. |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
72 |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
73 @cindex environment |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
74 Evaluation takes place in a context called the @dfn{environment}, |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
75 which consists of the current values and bindings of all Lisp |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
76 variables (@pxref{Variables}).@footnote{This definition of |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
77 ``environment'' is specifically not intended to include all the data |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
78 that can affect the result of a program.} Whenever a form refers to a |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
79 variable without creating a new binding for it, the variable evaluates |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
80 to the value given by the current environment. Evaluating a form may |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
81 create a new environment for recursive evaluation, by binding |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
82 variables (@pxref{Local Variables}). Such environments are temporary, |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
83 and vanish when the evaluation of the form is complete. |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
84 |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
85 @cindex side effect |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
86 Evaluating a form may also make changes that persist; these changes |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
87 are called @dfn{side effects}. An example of a form that produces a |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
88 side effect is @code{(setq foo 1)}. |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
89 |
84066 | 90 Do not confuse evaluation with command key interpretation. The |
91 editor command loop translates keyboard input into a command (an | |
92 interactively callable function) using the active keymaps, and then | |
102222
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
93 uses @code{call-interactively} to execute that command. Executing the |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
94 command usually involves evaluation, if the command is written in |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
95 Lisp; however, this step is not considered a part of command key |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
96 interpretation. @xref{Command Loop}. |
84066 | 97 |
98 @node Forms | |
99 @section Kinds of Forms | |
100 | |
101 A Lisp object that is intended to be evaluated is called a @dfn{form}. | |
102 How Emacs evaluates a form depends on its data type. Emacs has three | |
103 different kinds of form that are evaluated differently: symbols, lists, | |
104 and ``all other types.'' This section describes all three kinds, one by | |
105 one, starting with the ``all other types'' which are self-evaluating | |
106 forms. | |
107 | |
108 @menu | |
109 * Self-Evaluating Forms:: Forms that evaluate to themselves. | |
110 * Symbol Forms:: Symbols evaluate as variables. | |
111 * Classifying Lists:: How to distinguish various sorts of list forms. | |
112 * Function Indirection:: When a symbol appears as the car of a list, | |
113 we find the real function via the symbol. | |
114 * Function Forms:: Forms that call functions. | |
115 * Macro Forms:: Forms that call macros. | |
116 * Special Forms:: "Special forms" are idiosyncratic primitives, | |
117 most of them extremely important. | |
118 * Autoloading:: Functions set up to load files | |
119 containing their real definitions. | |
120 @end menu | |
121 | |
122 @node Self-Evaluating Forms | |
123 @subsection Self-Evaluating Forms | |
124 @cindex vector evaluation | |
125 @cindex literal evaluation | |
126 @cindex self-evaluating form | |
127 | |
102222
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
128 A @dfn{self-evaluating form} is any form that is not a list or |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
129 symbol. Self-evaluating forms evaluate to themselves: the result of |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
130 evaluation is the same object that was evaluated. Thus, the number 25 |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
131 evaluates to 25, and the string @code{"foo"} evaluates to the string |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
132 @code{"foo"}. Likewise, evaluating a vector does not cause evaluation |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
133 of the elements of the vector---it returns the same vector with its |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
134 contents unchanged. |
84066 | 135 |
136 @example | |
137 @group | |
138 '123 ; @r{A number, shown without evaluation.} | |
139 @result{} 123 | |
140 @end group | |
141 @group | |
142 123 ; @r{Evaluated as usual---result is the same.} | |
143 @result{} 123 | |
144 @end group | |
145 @group | |
146 (eval '123) ; @r{Evaluated ``by hand''---result is the same.} | |
147 @result{} 123 | |
148 @end group | |
149 @group | |
150 (eval (eval '123)) ; @r{Evaluating twice changes nothing.} | |
151 @result{} 123 | |
152 @end group | |
153 @end example | |
154 | |
155 It is common to write numbers, characters, strings, and even vectors | |
156 in Lisp code, taking advantage of the fact that they self-evaluate. | |
157 However, it is quite unusual to do this for types that lack a read | |
158 syntax, because there's no way to write them textually. It is possible | |
159 to construct Lisp expressions containing these types by means of a Lisp | |
160 program. Here is an example: | |
161 | |
162 @example | |
163 @group | |
164 ;; @r{Build an expression containing a buffer object.} | |
165 (setq print-exp (list 'print (current-buffer))) | |
166 @result{} (print #<buffer eval.texi>) | |
167 @end group | |
168 @group | |
169 ;; @r{Evaluate it.} | |
170 (eval print-exp) | |
171 @print{} #<buffer eval.texi> | |
172 @result{} #<buffer eval.texi> | |
173 @end group | |
174 @end example | |
175 | |
176 @node Symbol Forms | |
177 @subsection Symbol Forms | |
178 @cindex symbol evaluation | |
179 | |
180 When a symbol is evaluated, it is treated as a variable. The result | |
181 is the variable's value, if it has one. If it has none (if its value | |
182 cell is void), an error is signaled. For more information on the use of | |
183 variables, see @ref{Variables}. | |
184 | |
185 In the following example, we set the value of a symbol with | |
186 @code{setq}. Then we evaluate the symbol, and get back the value that | |
187 @code{setq} stored. | |
188 | |
189 @example | |
190 @group | |
191 (setq a 123) | |
192 @result{} 123 | |
193 @end group | |
194 @group | |
195 (eval 'a) | |
196 @result{} 123 | |
197 @end group | |
198 @group | |
199 a | |
200 @result{} 123 | |
201 @end group | |
202 @end example | |
203 | |
204 The symbols @code{nil} and @code{t} are treated specially, so that the | |
205 value of @code{nil} is always @code{nil}, and the value of @code{t} is | |
206 always @code{t}; you cannot set or bind them to any other values. Thus, | |
207 these two symbols act like self-evaluating forms, even though | |
208 @code{eval} treats them like any other symbol. A symbol whose name | |
209 starts with @samp{:} also self-evaluates in the same way; likewise, | |
210 its value ordinarily cannot be changed. @xref{Constant Variables}. | |
211 | |
212 @node Classifying Lists | |
213 @subsection Classification of List Forms | |
214 @cindex list form evaluation | |
215 | |
216 A form that is a nonempty list is either a function call, a macro | |
217 call, or a special form, according to its first element. These three | |
218 kinds of forms are evaluated in different ways, described below. The | |
219 remaining list elements constitute the @dfn{arguments} for the function, | |
220 macro, or special form. | |
221 | |
222 The first step in evaluating a nonempty list is to examine its first | |
223 element. This element alone determines what kind of form the list is | |
224 and how the rest of the list is to be processed. The first element is | |
225 @emph{not} evaluated, as it would be in some Lisp dialects such as | |
226 Scheme. | |
227 | |
228 @node Function Indirection | |
229 @subsection Symbol Function Indirection | |
230 @cindex symbol function indirection | |
231 @cindex indirection for functions | |
232 @cindex void function | |
233 | |
102222
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
234 If the first element of the list is a symbol then evaluation |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
235 examines the symbol's function cell, and uses its contents instead of |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
236 the original symbol. If the contents are another symbol, this |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
237 process, called @dfn{symbol function indirection}, is repeated until |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
238 it obtains a non-symbol. @xref{Function Names}, for more information |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
239 about symbol function indirection. |
84066 | 240 |
241 One possible consequence of this process is an infinite loop, in the | |
242 event that a symbol's function cell refers to the same symbol. Or a | |
243 symbol may have a void function cell, in which case the subroutine | |
244 @code{symbol-function} signals a @code{void-function} error. But if | |
245 neither of these things happens, we eventually obtain a non-symbol, | |
246 which ought to be a function or other suitable object. | |
247 | |
248 @kindex invalid-function | |
249 More precisely, we should now have a Lisp function (a lambda | |
102222
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
250 expression), a byte-code function, a primitive function, a Lisp macro, |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
251 a special form, or an autoload object. Each of these types is a case |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
252 described in one of the following sections. If the object is not one |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
253 of these types, Emacs signals an @code{invalid-function} error. |
84066 | 254 |
255 The following example illustrates the symbol indirection process. We | |
256 use @code{fset} to set the function cell of a symbol and | |
257 @code{symbol-function} to get the function cell contents | |
258 (@pxref{Function Cells}). Specifically, we store the symbol @code{car} | |
259 into the function cell of @code{first}, and the symbol @code{first} into | |
260 the function cell of @code{erste}. | |
261 | |
262 @smallexample | |
263 @group | |
264 ;; @r{Build this function cell linkage:} | |
265 ;; ------------- ----- ------- ------- | |
266 ;; | #<subr car> | <-- | car | <-- | first | <-- | erste | | |
267 ;; ------------- ----- ------- ------- | |
268 @end group | |
269 @end smallexample | |
270 | |
271 @smallexample | |
272 @group | |
273 (symbol-function 'car) | |
274 @result{} #<subr car> | |
275 @end group | |
276 @group | |
277 (fset 'first 'car) | |
278 @result{} car | |
279 @end group | |
280 @group | |
281 (fset 'erste 'first) | |
282 @result{} first | |
283 @end group | |
284 @group | |
285 (erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.} | |
286 @result{} 1 | |
287 @end group | |
288 @end smallexample | |
289 | |
290 By contrast, the following example calls a function without any symbol | |
291 function indirection, because the first element is an anonymous Lisp | |
292 function, not a symbol. | |
293 | |
294 @smallexample | |
295 @group | |
296 ((lambda (arg) (erste arg)) | |
297 '(1 2 3)) | |
298 @result{} 1 | |
299 @end group | |
300 @end smallexample | |
301 | |
302 @noindent | |
303 Executing the function itself evaluates its body; this does involve | |
304 symbol function indirection when calling @code{erste}. | |
305 | |
306 The built-in function @code{indirect-function} provides an easy way to | |
307 perform symbol function indirection explicitly. | |
308 | |
309 @c Emacs 19 feature | |
310 @defun indirect-function function &optional noerror | |
311 @anchor{Definition of indirect-function} | |
312 This function returns the meaning of @var{function} as a function. If | |
313 @var{function} is a symbol, then it finds @var{function}'s function | |
314 definition and starts over with that value. If @var{function} is not a | |
315 symbol, then it returns @var{function} itself. | |
316 | |
317 This function signals a @code{void-function} error if the final symbol | |
318 is unbound and optional argument @var{noerror} is @code{nil} or | |
319 omitted. Otherwise, if @var{noerror} is non-@code{nil}, it returns | |
320 @code{nil} if the final symbol is unbound. | |
321 | |
322 It signals a @code{cyclic-function-indirection} error if there is a | |
323 loop in the chain of symbols. | |
324 | |
325 Here is how you could define @code{indirect-function} in Lisp: | |
326 | |
327 @smallexample | |
328 (defun indirect-function (function) | |
329 (if (symbolp function) | |
330 (indirect-function (symbol-function function)) | |
331 function)) | |
332 @end smallexample | |
333 @end defun | |
334 | |
335 @node Function Forms | |
336 @subsection Evaluation of Function Forms | |
337 @cindex function form evaluation | |
338 @cindex function call | |
339 | |
340 If the first element of a list being evaluated is a Lisp function | |
341 object, byte-code object or primitive function object, then that list is | |
342 a @dfn{function call}. For example, here is a call to the function | |
343 @code{+}: | |
344 | |
345 @example | |
346 (+ 1 x) | |
347 @end example | |
348 | |
349 The first step in evaluating a function call is to evaluate the | |
350 remaining elements of the list from left to right. The results are the | |
351 actual argument values, one value for each list element. The next step | |
352 is to call the function with this list of arguments, effectively using | |
353 the function @code{apply} (@pxref{Calling Functions}). If the function | |
354 is written in Lisp, the arguments are used to bind the argument | |
355 variables of the function (@pxref{Lambda Expressions}); then the forms | |
356 in the function body are evaluated in order, and the value of the last | |
357 body form becomes the value of the function call. | |
358 | |
359 @node Macro Forms | |
360 @subsection Lisp Macro Evaluation | |
361 @cindex macro call evaluation | |
362 | |
363 If the first element of a list being evaluated is a macro object, then | |
364 the list is a @dfn{macro call}. When a macro call is evaluated, the | |
365 elements of the rest of the list are @emph{not} initially evaluated. | |
366 Instead, these elements themselves are used as the arguments of the | |
367 macro. The macro definition computes a replacement form, called the | |
368 @dfn{expansion} of the macro, to be evaluated in place of the original | |
369 form. The expansion may be any sort of form: a self-evaluating | |
370 constant, a symbol, or a list. If the expansion is itself a macro call, | |
371 this process of expansion repeats until some other sort of form results. | |
372 | |
373 Ordinary evaluation of a macro call finishes by evaluating the | |
374 expansion. However, the macro expansion is not necessarily evaluated | |
375 right away, or at all, because other programs also expand macro calls, | |
376 and they may or may not evaluate the expansions. | |
377 | |
378 Normally, the argument expressions are not evaluated as part of | |
379 computing the macro expansion, but instead appear as part of the | |
380 expansion, so they are computed when the expansion is evaluated. | |
381 | |
382 For example, given a macro defined as follows: | |
383 | |
384 @example | |
385 @group | |
386 (defmacro cadr (x) | |
387 (list 'car (list 'cdr x))) | |
388 @end group | |
389 @end example | |
390 | |
391 @noindent | |
392 an expression such as @code{(cadr (assq 'handler list))} is a macro | |
393 call, and its expansion is: | |
394 | |
395 @example | |
396 (car (cdr (assq 'handler list))) | |
397 @end example | |
398 | |
399 @noindent | |
400 Note that the argument @code{(assq 'handler list)} appears in the | |
401 expansion. | |
402 | |
403 @xref{Macros}, for a complete description of Emacs Lisp macros. | |
404 | |
405 @node Special Forms | |
406 @subsection Special Forms | |
98686
2a93b311de33
* objects.texi (Primitive Function Type): Move "@cindex special forms" from here...
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
407 @cindex special forms |
2a93b311de33
* objects.texi (Primitive Function Type): Move "@cindex special forms" from here...
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
408 @cindex evaluation of special forms |
84066 | 409 |
410 A @dfn{special form} is a primitive function specially marked so that | |
411 its arguments are not all evaluated. Most special forms define control | |
412 structures or perform variable bindings---things which functions cannot | |
413 do. | |
414 | |
415 Each special form has its own rules for which arguments are evaluated | |
416 and which are used without evaluation. Whether a particular argument is | |
417 evaluated may depend on the results of evaluating other arguments. | |
418 | |
419 Here is a list, in alphabetical order, of all of the special forms in | |
420 Emacs Lisp with a reference to where each is described. | |
421 | |
422 @table @code | |
423 @item and | |
424 @pxref{Combining Conditions} | |
425 | |
426 @item catch | |
427 @pxref{Catch and Throw} | |
428 | |
429 @item cond | |
430 @pxref{Conditionals} | |
431 | |
432 @item condition-case | |
433 @pxref{Handling Errors} | |
434 | |
435 @item defconst | |
436 @pxref{Defining Variables} | |
437 | |
438 @item defmacro | |
439 @pxref{Defining Macros} | |
440 | |
441 @item defun | |
442 @pxref{Defining Functions} | |
443 | |
444 @item defvar | |
445 @pxref{Defining Variables} | |
446 | |
447 @item function | |
448 @pxref{Anonymous Functions} | |
449 | |
450 @item if | |
451 @pxref{Conditionals} | |
452 | |
453 @item interactive | |
454 @pxref{Interactive Call} | |
455 | |
456 @item let | |
457 @itemx let* | |
458 @pxref{Local Variables} | |
459 | |
460 @item or | |
461 @pxref{Combining Conditions} | |
462 | |
463 @item prog1 | |
464 @itemx prog2 | |
465 @itemx progn | |
466 @pxref{Sequencing} | |
467 | |
468 @item quote | |
469 @pxref{Quoting} | |
470 | |
471 @item save-current-buffer | |
472 @pxref{Current Buffer} | |
473 | |
474 @item save-excursion | |
475 @pxref{Excursions} | |
476 | |
477 @item save-restriction | |
478 @pxref{Narrowing} | |
479 | |
480 @item save-window-excursion | |
481 @pxref{Window Configurations} | |
482 | |
483 @item setq | |
484 @pxref{Setting Variables} | |
485 | |
486 @item setq-default | |
487 @pxref{Creating Buffer-Local} | |
488 | |
489 @item track-mouse | |
490 @pxref{Mouse Tracking} | |
491 | |
492 @item unwind-protect | |
493 @pxref{Nonlocal Exits} | |
494 | |
495 @item while | |
496 @pxref{Iteration} | |
497 | |
498 @item with-output-to-temp-buffer | |
499 @pxref{Temporary Displays} | |
500 @end table | |
501 | |
502 @cindex CL note---special forms compared | |
503 @quotation | |
504 @b{Common Lisp note:} Here are some comparisons of special forms in | |
505 GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and | |
506 @code{catch} are special forms in both Emacs Lisp and Common Lisp. | |
507 @code{defun} is a special form in Emacs Lisp, but a macro in Common | |
508 Lisp. @code{save-excursion} is a special form in Emacs Lisp, but | |
509 doesn't exist in Common Lisp. @code{throw} is a special form in | |
510 Common Lisp (because it must be able to throw multiple values), but it | |
511 is a function in Emacs Lisp (which doesn't have multiple | |
512 values).@refill | |
513 @end quotation | |
514 | |
515 @node Autoloading | |
516 @subsection Autoloading | |
517 | |
518 The @dfn{autoload} feature allows you to call a function or macro | |
519 whose function definition has not yet been loaded into Emacs. It | |
520 specifies which file contains the definition. When an autoload object | |
521 appears as a symbol's function definition, calling that symbol as a | |
522 function automatically loads the specified file; then it calls the real | |
523 definition loaded from that file. @xref{Autoload}. | |
524 | |
525 @node Quoting | |
526 @section Quoting | |
527 | |
528 The special form @code{quote} returns its single argument, as written, | |
529 without evaluating it. This provides a way to include constant symbols | |
530 and lists, which are not self-evaluating objects, in a program. (It is | |
531 not necessary to quote self-evaluating objects such as numbers, strings, | |
532 and vectors.) | |
533 | |
534 @defspec quote object | |
535 This special form returns @var{object}, without evaluating it. | |
536 @end defspec | |
537 | |
538 @cindex @samp{'} for quoting | |
539 @cindex quoting using apostrophe | |
540 @cindex apostrophe for quoting | |
541 Because @code{quote} is used so often in programs, Lisp provides a | |
542 convenient read syntax for it. An apostrophe character (@samp{'}) | |
543 followed by a Lisp object (in read syntax) expands to a list whose first | |
544 element is @code{quote}, and whose second element is the object. Thus, | |
545 the read syntax @code{'x} is an abbreviation for @code{(quote x)}. | |
546 | |
547 Here are some examples of expressions that use @code{quote}: | |
548 | |
549 @example | |
550 @group | |
551 (quote (+ 1 2)) | |
552 @result{} (+ 1 2) | |
553 @end group | |
554 @group | |
555 (quote foo) | |
556 @result{} foo | |
557 @end group | |
558 @group | |
559 'foo | |
560 @result{} foo | |
561 @end group | |
562 @group | |
563 ''foo | |
564 @result{} (quote foo) | |
565 @end group | |
566 @group | |
567 '(quote foo) | |
568 @result{} (quote foo) | |
569 @end group | |
570 @group | |
571 ['foo] | |
572 @result{} [(quote foo)] | |
573 @end group | |
574 @end example | |
575 | |
576 Other quoting constructs include @code{function} (@pxref{Anonymous | |
577 Functions}), which causes an anonymous lambda expression written in Lisp | |
578 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote | |
579 only part of a list, while computing and substituting other parts. | |
580 | |
581 @node Eval | |
582 @section Eval | |
583 | |
584 Most often, forms are evaluated automatically, by virtue of their | |
585 occurrence in a program being run. On rare occasions, you may need to | |
586 write code that evaluates a form that is computed at run time, such as | |
587 after reading a form from text being edited or getting one from a | |
588 property list. On these occasions, use the @code{eval} function. | |
589 | |
590 The functions and variables described in this section evaluate forms, | |
591 specify limits to the evaluation process, or record recently returned | |
592 values. Loading a file also does evaluation (@pxref{Loading}). | |
593 | |
594 It is generally cleaner and more flexible to store a function in a | |
595 data structure, and call it with @code{funcall} or @code{apply}, than | |
596 to store an expression in the data structure and evaluate it. Using | |
597 functions provides the ability to pass information to them as | |
598 arguments. | |
599 | |
600 @defun eval form | |
601 This is the basic function evaluating an expression. It evaluates | |
602 @var{form} in the current environment and returns the result. How the | |
603 evaluation proceeds depends on the type of the object (@pxref{Forms}). | |
604 | |
605 Since @code{eval} is a function, the argument expression that appears | |
606 in a call to @code{eval} is evaluated twice: once as preparation before | |
607 @code{eval} is called, and again by the @code{eval} function itself. | |
608 Here is an example: | |
609 | |
610 @example | |
611 @group | |
612 (setq foo 'bar) | |
613 @result{} bar | |
614 @end group | |
615 @group | |
616 (setq bar 'baz) | |
617 @result{} baz | |
618 ;; @r{Here @code{eval} receives argument @code{foo}} | |
619 (eval 'foo) | |
620 @result{} bar | |
621 ;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}} | |
622 (eval foo) | |
623 @result{} baz | |
624 @end group | |
625 @end example | |
626 | |
627 The number of currently active calls to @code{eval} is limited to | |
628 @code{max-lisp-eval-depth} (see below). | |
629 @end defun | |
630 | |
631 @deffn Command eval-region start end &optional stream read-function | |
632 @anchor{Definition of eval-region} | |
633 This function evaluates the forms in the current buffer in the region | |
634 defined by the positions @var{start} and @var{end}. It reads forms from | |
635 the region and calls @code{eval} on them until the end of the region is | |
636 reached, or until an error is signaled and not handled. | |
637 | |
638 By default, @code{eval-region} does not produce any output. However, | |
639 if @var{stream} is non-@code{nil}, any output produced by output | |
640 functions (@pxref{Output Functions}), as well as the values that | |
641 result from evaluating the expressions in the region are printed using | |
642 @var{stream}. @xref{Output Streams}. | |
643 | |
644 If @var{read-function} is non-@code{nil}, it should be a function, | |
645 which is used instead of @code{read} to read expressions one by one. | |
646 This function is called with one argument, the stream for reading | |
647 input. You can also use the variable @code{load-read-function} | |
648 (@pxref{Definition of load-read-function,, How Programs Do Loading}) | |
649 to specify this function, but it is more robust to use the | |
650 @var{read-function} argument. | |
651 | |
652 @code{eval-region} does not move point. It always returns @code{nil}. | |
653 @end deffn | |
654 | |
655 @cindex evaluation of buffer contents | |
656 @deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print | |
657 This is similar to @code{eval-region}, but the arguments provide | |
658 different optional features. @code{eval-buffer} operates on the | |
659 entire accessible portion of buffer @var{buffer-or-name}. | |
660 @var{buffer-or-name} can be a buffer, a buffer name (a string), or | |
661 @code{nil} (or omitted), which means to use the current buffer. | |
662 @var{stream} is used as in @code{eval-region}, unless @var{stream} is | |
663 @code{nil} and @var{print} non-@code{nil}. In that case, values that | |
664 result from evaluating the expressions are still discarded, but the | |
665 output of the output functions is printed in the echo area. | |
666 @var{filename} is the file name to use for @code{load-history} | |
667 (@pxref{Unloading}), and defaults to @code{buffer-file-name} | |
668 (@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil}, | |
669 @code{read} converts strings to unibyte whenever possible. | |
670 | |
671 @findex eval-current-buffer | |
672 @code{eval-current-buffer} is an alias for this command. | |
673 @end deffn | |
674 | |
103273
c32ec20d0ab5
* abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents:
102222
diff
changeset
|
675 @defopt max-lisp-eval-depth |
84066 | 676 @anchor{Definition of max-lisp-eval-depth} |
677 This variable defines the maximum depth allowed in calls to @code{eval}, | |
678 @code{apply}, and @code{funcall} before an error is signaled (with error | |
679 message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). | |
680 | |
681 This limit, with the associated error when it is exceeded, is one way | |
682 Emacs Lisp avoids infinite recursion on an ill-defined function. If | |
683 you increase the value of @code{max-lisp-eval-depth} too much, such | |
684 code can cause stack overflow instead. | |
685 @cindex Lisp nesting error | |
686 | |
687 The depth limit counts internal uses of @code{eval}, @code{apply}, and | |
688 @code{funcall}, such as for calling the functions mentioned in Lisp | |
689 expressions, and recursive evaluation of function call arguments and | |
690 function body forms, as well as explicit calls in Lisp code. | |
691 | |
102222
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
692 The default value of this variable is 400. If you set it to a value |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
693 less than 100, Lisp will reset it to 100 if the given value is |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
694 reached. Entry to the Lisp debugger increases the value, if there is |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
695 little room left, to make sure the debugger itself has room to |
c20d14a01539
(Intro Eval): Copyedits. Standardize on "form" instead of "expression" throughout.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
696 execute. |
84066 | 697 |
698 @code{max-specpdl-size} provides another limit on nesting. | |
699 @xref{Definition of max-specpdl-size,, Local Variables}. | |
103273
c32ec20d0ab5
* abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents:
102222
diff
changeset
|
700 @end defopt |
84066 | 701 |
702 @defvar values | |
703 The value of this variable is a list of the values returned by all the | |
704 expressions that were read, evaluated, and printed from buffers | |
705 (including the minibuffer) by the standard Emacs commands which do | |
706 this. (Note that this does @emph{not} include evaluation in | |
707 @samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in | |
708 @code{lisp-interaction-mode}.) The elements are ordered most recent | |
709 first. | |
710 | |
711 @example | |
712 @group | |
713 (setq x 1) | |
714 @result{} 1 | |
715 @end group | |
716 @group | |
717 (list 'A (1+ 2) auto-save-default) | |
718 @result{} (A 3 t) | |
719 @end group | |
720 @group | |
721 values | |
722 @result{} ((A 3 t) 1 @dots{}) | |
723 @end group | |
724 @end example | |
725 | |
726 This variable is useful for referring back to values of forms recently | |
727 evaluated. It is generally a bad idea to print the value of | |
728 @code{values} itself, since this may be very long. Instead, examine | |
729 particular elements, like this: | |
730 | |
731 @example | |
732 @group | |
733 ;; @r{Refer to the most recent evaluation result.} | |
734 (nth 0 values) | |
735 @result{} (A 3 t) | |
736 @end group | |
737 @group | |
738 ;; @r{That put a new element on,} | |
739 ;; @r{so all elements move back one.} | |
740 (nth 1 values) | |
741 @result{} (A 3 t) | |
742 @end group | |
743 @group | |
744 ;; @r{This gets the element that was next-to-most-recent} | |
745 ;; @r{before this example.} | |
746 (nth 3 values) | |
747 @result{} 1 | |
748 @end group | |
749 @end example | |
750 @end defvar | |
751 | |
752 @ignore | |
753 arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57 | |
754 @end ignore |