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