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