*** empty log message ***
[emacs.git] / lispref / eval.texi
blob4c4e19b1a47db772f18722eaa57550905a38ca88
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 Free Software Foundation, Inc. 
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
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}.
21 @ifnottex
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).
26 * Eval::        How to invoke the Lisp interpreter explicitly.
27 @end menu
29 @node Intro Eval
30 @section Introduction to Evaluation
32   The Lisp interpreter, or evaluator, is the program that computes
33 the value of an expression that is given to it.  When a function 
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.
38   How the evaluator handles an object depends primarily on the data
39 type of the object.
40 @end ifnottex
42 @cindex forms
43 @cindex expression
44   A Lisp object that is intended for evaluation is called an
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.
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}.
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}.
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}.
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}).
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
86 specifically not intended to include all the data that can affect the
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}.
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)}.
99   The details of what evaluation means for each kind of form are
100 described below (@pxref{Forms}).
102 @node Forms
103 @section Kinds of Forms
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,
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.
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
126 @node Self-Evaluating Forms
127 @subsection Self-Evaluating Forms
128 @cindex vector evaluation
129 @cindex literal evaluation
130 @cindex self-evaluating form
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.
140 @example
141 @group
142 '123               ; @r{A number, shown without evaluation.}
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
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
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:
166 @example
167 @group
168 ;; @r{Build an expression containing a buffer object.}
169 (setq print-exp (list 'print (current-buffer)))
170      @result{} (print #<buffer eval.texi>)
171 @end group
172 @group
173 ;; @r{Evaluate it.}
174 (eval print-exp)
175      @print{} #<buffer eval.texi>
176      @result{} #<buffer eval.texi>
177 @end group
178 @end example
180 @node Symbol Forms
181 @subsection Symbol Forms
182 @cindex symbol evaluation
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}.
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.
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
204      @result{} 123
205 @end group
206 @end example
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
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
212 @code{eval} treats them like any other symbol.  A symbol whose name
213 starts with @samp{:} also self-evaluates in the same way; likewise,
214 its value ordinarily cannot be changed.  @xref{Constant Variables}.
216 @node Classifying Lists
217 @subsection Classification of List Forms
218 @cindex list form evaluation
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.
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.
232 @node Function Indirection
233 @subsection Symbol Function Indirection
234 @cindex symbol function indirection
235 @cindex indirection
236 @cindex void function
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.
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.
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.
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}.
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
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
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.
300 @smallexample
301 @group
302 ((lambda (arg) (erste arg))
303  '(1 2 3)) 
304      @result{} 1
305 @end group
306 @end smallexample
308 @noindent
309 Executing the function itself evaluates its body; this does involve
310 symbol function indirection when calling @code{erste}.
312   The built-in function @code{indirect-function} provides an easy way to
313 perform symbol function indirection explicitly.
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.
322 Here is how you could define @code{indirect-function} in Lisp:
324 @smallexample
325 (defun indirect-function (function)
326   (if (symbolp function)
327       (indirect-function (symbol-function function))
328     function))
329 @end smallexample
330 @end defun
332 @node Function Forms
333 @subsection Evaluation of Function Forms
334 @cindex function form evaluation
335 @cindex function call
337   If the first element of a list being evaluated is a Lisp function
338 object, byte-code object or primitive function object, then that list is
339 a @dfn{function call}.  For example, here is a call to the function
340 @code{+}:
342 @example
343 (+ 1 x)
344 @end example
346   The first step in evaluating a function call is to evaluate the
347 remaining elements of the list from left to right.  The results are the
348 actual argument values, one value for each list element.  The next step
349 is to call the function with this list of arguments, effectively using
350 the function @code{apply} (@pxref{Calling Functions}).  If the function
351 is written in Lisp, the arguments are used to bind the argument
352 variables of the function (@pxref{Lambda Expressions}); then the forms
353 in the function body are evaluated in order, and the value of the last
354 body form becomes the value of the function call.
356 @node Macro Forms
357 @subsection Lisp Macro Evaluation
358 @cindex macro call evaluation
360   If the first element of a list being evaluated is a macro object, then
361 the list is a @dfn{macro call}.  When a macro call is evaluated, the
362 elements of the rest of the list are @emph{not} initially evaluated.
363 Instead, these elements themselves are used as the arguments of the
364 macro.  The macro definition computes a replacement form, called the
365 @dfn{expansion} of the macro, to be evaluated in place of the original
366 form.  The expansion may be any sort of form: a self-evaluating
367 constant, a symbol, or a list.  If the expansion is itself a macro call,
368 this process of expansion repeats until some other sort of form results.
370   Ordinary evaluation of a macro call finishes by evaluating the
371 expansion.  However, the macro expansion is not necessarily evaluated
372 right away, or at all, because other programs also expand macro calls,
373 and they may or may not evaluate the expansions.
375   Normally, the argument expressions are not evaluated as part of
376 computing the macro expansion, but instead appear as part of the
377 expansion, so they are computed when the expansion is evaluated.
379   For example, given a macro defined as follows:
381 @example
382 @group
383 (defmacro cadr (x)
384   (list 'car (list 'cdr x)))
385 @end group
386 @end example
388 @noindent
389 an expression such as @code{(cadr (assq 'handler list))} is a macro
390 call, and its expansion is:
392 @example
393 (car (cdr (assq 'handler list)))
394 @end example
396 @noindent
397 Note that the argument @code{(assq 'handler list)} appears in the
398 expansion.
400 @xref{Macros}, for a complete description of Emacs Lisp macros.
402 @node Special Forms
403 @subsection Special Forms
404 @cindex special form evaluation
406   A @dfn{special form} is a primitive function specially marked so that
407 its arguments are not all evaluated.  Most special forms define control
408 structures or perform variable bindings---things which functions cannot
411   Each special form has its own rules for which arguments are evaluated
412 and which are used without evaluation.  Whether a particular argument is
413 evaluated may depend on the results of evaluating other arguments.
415   Here is a list, in alphabetical order, of all of the special forms in
416 Emacs Lisp with a reference to where each is described.
418 @table @code
419 @item and
420 @pxref{Combining Conditions}
422 @item catch
423 @pxref{Catch and Throw}
425 @item cond
426 @pxref{Conditionals}
428 @item condition-case
429 @pxref{Handling Errors}
431 @item defconst
432 @pxref{Defining Variables}
434 @item defmacro
435 @pxref{Defining Macros}
437 @item defun
438 @pxref{Defining Functions}
440 @item defvar
441 @pxref{Defining Variables}
443 @item function
444 @pxref{Anonymous Functions}
446 @item if
447 @pxref{Conditionals}
449 @item interactive
450 @pxref{Interactive Call}
452 @item let
453 @itemx let*
454 @pxref{Local Variables}
456 @item or
457 @pxref{Combining Conditions}
459 @item prog1
460 @itemx prog2
461 @itemx progn
462 @pxref{Sequencing}
464 @item quote
465 @pxref{Quoting}
467 @item save-current-buffer
468 @pxref{Current Buffer}
470 @item save-excursion
471 @pxref{Excursions}
473 @item save-restriction
474 @pxref{Narrowing}
476 @item save-window-excursion
477 @pxref{Window Configurations}
479 @item setq
480 @pxref{Setting Variables}
482 @item setq-default
483 @pxref{Creating Buffer-Local}
485 @item track-mouse
486 @pxref{Mouse Tracking}
488 @item unwind-protect
489 @pxref{Nonlocal Exits}
491 @item while
492 @pxref{Iteration}
494 @item with-output-to-temp-buffer
495 @pxref{Temporary Displays}
496 @end table
498 @cindex CL note---special forms compared
499 @quotation
500 @b{Common Lisp note:} Here are some comparisons of special forms in
501 GNU Emacs Lisp and Common Lisp.  @code{setq}, @code{if}, and
502 @code{catch} are special forms in both Emacs Lisp and Common Lisp.
503 @code{defun} is a special form in Emacs Lisp, but a macro in Common
504 Lisp.  @code{save-excursion} is a special form in Emacs Lisp, but
505 doesn't exist in Common Lisp.  @code{throw} is a special form in
506 Common Lisp (because it must be able to throw multiple values), but it
507 is a function in Emacs Lisp (which doesn't have multiple
508 values).@refill
509 @end quotation
511 @node Autoloading
512 @subsection Autoloading
514   The @dfn{autoload} feature allows you to call a function or macro
515 whose function definition has not yet been loaded into Emacs.  It
516 specifies which file contains the definition.  When an autoload object
517 appears as a symbol's function definition, calling that symbol as a
518 function automatically loads the specified file; then it calls the real
519 definition loaded from that file.  @xref{Autoload}.
521 @node Quoting
522 @section Quoting
523 @cindex quoting
525   The special form @code{quote} returns its single argument, as written,
526 without evaluating it.  This provides a way to include constant symbols
527 and lists, which are not self-evaluating objects, in a program.  (It is
528 not necessary to quote self-evaluating objects such as numbers, strings,
529 and vectors.)
531 @defspec quote object
532 This special form returns @var{object}, without evaluating it.
533 @end defspec
535 @cindex @samp{'} for quoting
536 @cindex quoting using apostrophe
537 @cindex apostrophe for quoting
538 Because @code{quote} is used so often in programs, Lisp provides a
539 convenient read syntax for it.  An apostrophe character (@samp{'})
540 followed by a Lisp object (in read syntax) expands to a list whose first
541 element is @code{quote}, and whose second element is the object.  Thus,
542 the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
544 Here are some examples of expressions that use @code{quote}:
546 @example
547 @group
548 (quote (+ 1 2))
549      @result{} (+ 1 2)
550 @end group
551 @group
552 (quote foo)
553      @result{} foo
554 @end group
555 @group
556 'foo
557      @result{} foo
558 @end group
559 @group
560 ''foo
561      @result{} (quote foo)
562 @end group
563 @group
564 '(quote foo)
565      @result{} (quote foo)
566 @end group
567 @group
568 ['foo]
569      @result{} [(quote foo)]
570 @end group
571 @end example
573   Other quoting constructs include @code{function} (@pxref{Anonymous
574 Functions}), which causes an anonymous lambda expression written in Lisp
575 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
576 only part of a list, while computing and substituting other parts.
578 @node Eval
579 @section Eval
581   Most often, forms are evaluated automatically, by virtue of their
582 occurrence in a program being run.  On rare occasions, you may need to
583 write code that evaluates a form that is computed at run time, such as
584 after reading a form from text being edited or getting one from a
585 property list.  On these occasions, use the @code{eval} function.
587   The functions and variables described in this section evaluate forms,
588 specify limits to the evaluation process, or record recently returned
589 values.  Loading a file also does evaluation (@pxref{Loading}).
591   @strong{Note:} it is generally cleaner and more flexible to store a
592 function in a data structure, and call it with @code{funcall} or
593 @code{apply}, than to store an expression in the data structure and
594 evaluate it.  Using functions provides the ability to pass information
595 to them as arguments.
597 @defun eval form
598 This is the basic function evaluating an expression.  It evaluates
599 @var{form} in the current environment and returns the result.  How the
600 evaluation proceeds depends on the type of the object (@pxref{Forms}).
602 Since @code{eval} is a function, the argument expression that appears
603 in a call to @code{eval} is evaluated twice: once as preparation before
604 @code{eval} is called, and again by the @code{eval} function itself.
605 Here is an example:
607 @example
608 @group
609 (setq foo 'bar)
610      @result{} bar
611 @end group
612 @group
613 (setq bar 'baz)
614      @result{} baz
615 ;; @r{Here @code{eval} receives argument @code{foo}}
616 (eval 'foo)
617      @result{} bar
618 ;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}
619 (eval foo)
620      @result{} baz
621 @end group
622 @end example
624 The number of currently active calls to @code{eval} is limited to
625 @code{max-lisp-eval-depth} (see below).
626 @end defun
628 @deffn Command eval-region start end &optional stream read-function
629 This function evaluates the forms in the current buffer in the region
630 defined by the positions @var{start} and @var{end}.  It reads forms from
631 the region and calls @code{eval} on them until the end of the region is
632 reached, or until an error is signaled and not handled.
634 If @var{stream} is non-@code{nil}, the values that result from
635 evaluating the expressions in the region are printed using @var{stream}.
636 @xref{Output Streams}.
638 If @var{read-function} is non-@code{nil}, it should be a function, which
639 is used instead of @code{read} to read expressions one by one.  This
640 function is called with one argument, the stream for reading input.  You
641 can also use the variable @code{load-read-function} (@pxref{How Programs
642 Do Loading}) to specify this function, but it is more robust to use the
643 @var{read-function} argument.
645 @code{eval-region} always returns @code{nil}.
646 @end deffn
648 @cindex evaluation of buffer contents
649 @deffn Command eval-current-buffer &optional stream
650 This is like @code{eval-region} except that it operates on the whole
651 buffer.
652 @end deffn
654 @defvar max-lisp-eval-depth
655 This variable defines the maximum depth allowed in calls to @code{eval},
656 @code{apply}, and @code{funcall} before an error is signaled (with error
657 message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).  This limit,
658 with the associated error when it is exceeded, is one way that Lisp
659 avoids infinite recursion on an ill-defined function.
660 @cindex Lisp nesting error
662 The depth limit counts internal uses of @code{eval}, @code{apply}, and
663 @code{funcall}, such as for calling the functions mentioned in Lisp
664 expressions, and recursive evaluation of function call arguments and
665 function body forms, as well as explicit calls in Lisp code.
667 The default value of this variable is 300.  If you set it to a value
668 less than 100, Lisp will reset it to 100 if the given value is reached.
669 Entry to the Lisp debugger increases the value, if there is little room
670 left, to make sure the debugger itself has room to execute.
672 @code{max-specpdl-size} provides another limit on nesting.
673 @xref{Local Variables}.
674 @end defvar
676 @defvar values
677 The value of this variable is a list of the values returned by all the
678 expressions that were read, evaluated, and printed from buffers
679 (including the minibuffer) by the standard Emacs commands which do this.
680 The elements are ordered most recent first.
682 @example
683 @group
684 (setq x 1)
685      @result{} 1
686 @end group
687 @group
688 (list 'A (1+ 2) auto-save-default)
689      @result{} (A 3 t)
690 @end group
691 @group
692 values
693      @result{} ((A 3 t) 1 @dots{})
694 @end group
695 @end example
697 This variable is useful for referring back to values of forms recently
698 evaluated.  It is generally a bad idea to print the value of
699 @code{values} itself, since this may be very long.  Instead, examine
700 particular elements, like this:
702 @example
703 @group
704 ;; @r{Refer to the most recent evaluation result.}
705 (nth 0 values)
706      @result{} (A 3 t)
707 @end group
708 @group
709 ;; @r{That put a new element on,}
710 ;;   @r{so all elements move back one.}
711 (nth 1 values)
712      @result{} (A 3 t)
713 @end group
714 @group
715 ;; @r{This gets the element that was next-to-most-recent}
716 ;;   @r{before this example.}
717 (nth 3 values)
718      @result{} 1
719 @end group
720 @end example
721 @end defvar