*** empty log message ***
[emacs.git] / lispref / eval.texi
blob6a43466af67371e4b8eddd506931457b622e758d
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, 2003, 2004 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 @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.
323 This function signals a @code{void-function} error if the final
324 symbol is unbound and a @code{cyclic-function-indirection} error if
325 there is a loop in the chain of symbols.
327 Here is how you could define @code{indirect-function} in Lisp:
329 @smallexample
330 (defun indirect-function (function)
331   (if (symbolp function)
332       (indirect-function (symbol-function function))
333     function))
334 @end smallexample
335 @end defun
337 @node Function Forms
338 @subsection Evaluation of Function Forms
339 @cindex function form evaluation
340 @cindex function call
342   If the first element of a list being evaluated is a Lisp function
343 object, byte-code object or primitive function object, then that list is
344 a @dfn{function call}.  For example, here is a call to the function
345 @code{+}:
347 @example
348 (+ 1 x)
349 @end example
351   The first step in evaluating a function call is to evaluate the
352 remaining elements of the list from left to right.  The results are the
353 actual argument values, one value for each list element.  The next step
354 is to call the function with this list of arguments, effectively using
355 the function @code{apply} (@pxref{Calling Functions}).  If the function
356 is written in Lisp, the arguments are used to bind the argument
357 variables of the function (@pxref{Lambda Expressions}); then the forms
358 in the function body are evaluated in order, and the value of the last
359 body form becomes the value of the function call.
361 @node Macro Forms
362 @subsection Lisp Macro Evaluation
363 @cindex macro call evaluation
365   If the first element of a list being evaluated is a macro object, then
366 the list is a @dfn{macro call}.  When a macro call is evaluated, the
367 elements of the rest of the list are @emph{not} initially evaluated.
368 Instead, these elements themselves are used as the arguments of the
369 macro.  The macro definition computes a replacement form, called the
370 @dfn{expansion} of the macro, to be evaluated in place of the original
371 form.  The expansion may be any sort of form: a self-evaluating
372 constant, a symbol, or a list.  If the expansion is itself a macro call,
373 this process of expansion repeats until some other sort of form results.
375   Ordinary evaluation of a macro call finishes by evaluating the
376 expansion.  However, the macro expansion is not necessarily evaluated
377 right away, or at all, because other programs also expand macro calls,
378 and they may or may not evaluate the expansions.
380   Normally, the argument expressions are not evaluated as part of
381 computing the macro expansion, but instead appear as part of the
382 expansion, so they are computed when the expansion is evaluated.
384   For example, given a macro defined as follows:
386 @example
387 @group
388 (defmacro cadr (x)
389   (list 'car (list 'cdr x)))
390 @end group
391 @end example
393 @noindent
394 an expression such as @code{(cadr (assq 'handler list))} is a macro
395 call, and its expansion is:
397 @example
398 (car (cdr (assq 'handler list)))
399 @end example
401 @noindent
402 Note that the argument @code{(assq 'handler list)} appears in the
403 expansion.
405 @xref{Macros}, for a complete description of Emacs Lisp macros.
407 @node Special Forms
408 @subsection Special Forms
409 @cindex special form evaluation
411   A @dfn{special form} is a primitive function specially marked so that
412 its arguments are not all evaluated.  Most special forms define control
413 structures or perform variable bindings---things which functions cannot
416   Each special form has its own rules for which arguments are evaluated
417 and which are used without evaluation.  Whether a particular argument is
418 evaluated may depend on the results of evaluating other arguments.
420   Here is a list, in alphabetical order, of all of the special forms in
421 Emacs Lisp with a reference to where each is described.
423 @table @code
424 @item and
425 @pxref{Combining Conditions}
427 @item catch
428 @pxref{Catch and Throw}
430 @item cond
431 @pxref{Conditionals}
433 @item condition-case
434 @pxref{Handling Errors}
436 @item defconst
437 @pxref{Defining Variables}
439 @item defmacro
440 @pxref{Defining Macros}
442 @item defun
443 @pxref{Defining Functions}
445 @item defvar
446 @pxref{Defining Variables}
448 @item function
449 @pxref{Anonymous Functions}
451 @item if
452 @pxref{Conditionals}
454 @item interactive
455 @pxref{Interactive Call}
457 @item let
458 @itemx let*
459 @pxref{Local Variables}
461 @item or
462 @pxref{Combining Conditions}
464 @item prog1
465 @itemx prog2
466 @itemx progn
467 @pxref{Sequencing}
469 @item quote
470 @pxref{Quoting}
472 @item save-current-buffer
473 @pxref{Current Buffer}
475 @item save-excursion
476 @pxref{Excursions}
478 @item save-restriction
479 @pxref{Narrowing}
481 @item save-window-excursion
482 @pxref{Window Configurations}
484 @item setq
485 @pxref{Setting Variables}
487 @item setq-default
488 @pxref{Creating Buffer-Local}
490 @item track-mouse
491 @pxref{Mouse Tracking}
493 @item unwind-protect
494 @pxref{Nonlocal Exits}
496 @item while
497 @pxref{Iteration}
499 @item with-output-to-temp-buffer
500 @pxref{Temporary Displays}
501 @end table
503 @cindex CL note---special forms compared
504 @quotation
505 @b{Common Lisp note:} Here are some comparisons of special forms in
506 GNU Emacs Lisp and Common Lisp.  @code{setq}, @code{if}, and
507 @code{catch} are special forms in both Emacs Lisp and Common Lisp.
508 @code{defun} is a special form in Emacs Lisp, but a macro in Common
509 Lisp.  @code{save-excursion} is a special form in Emacs Lisp, but
510 doesn't exist in Common Lisp.  @code{throw} is a special form in
511 Common Lisp (because it must be able to throw multiple values), but it
512 is a function in Emacs Lisp (which doesn't have multiple
513 values).@refill
514 @end quotation
516 @node Autoloading
517 @subsection Autoloading
519   The @dfn{autoload} feature allows you to call a function or macro
520 whose function definition has not yet been loaded into Emacs.  It
521 specifies which file contains the definition.  When an autoload object
522 appears as a symbol's function definition, calling that symbol as a
523 function automatically loads the specified file; then it calls the real
524 definition loaded from that file.  @xref{Autoload}.
526 @node Quoting
527 @section Quoting
528 @cindex quoting
530   The special form @code{quote} returns its single argument, as written,
531 without evaluating it.  This provides a way to include constant symbols
532 and lists, which are not self-evaluating objects, in a program.  (It is
533 not necessary to quote self-evaluating objects such as numbers, strings,
534 and vectors.)
536 @defspec quote object
537 This special form returns @var{object}, without evaluating it.
538 @end defspec
540 @cindex @samp{'} for quoting
541 @cindex quoting using apostrophe
542 @cindex apostrophe for quoting
543 Because @code{quote} is used so often in programs, Lisp provides a
544 convenient read syntax for it.  An apostrophe character (@samp{'})
545 followed by a Lisp object (in read syntax) expands to a list whose first
546 element is @code{quote}, and whose second element is the object.  Thus,
547 the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
549 Here are some examples of expressions that use @code{quote}:
551 @example
552 @group
553 (quote (+ 1 2))
554      @result{} (+ 1 2)
555 @end group
556 @group
557 (quote foo)
558      @result{} foo
559 @end group
560 @group
561 'foo
562      @result{} foo
563 @end group
564 @group
565 ''foo
566      @result{} (quote foo)
567 @end group
568 @group
569 '(quote foo)
570      @result{} (quote foo)
571 @end group
572 @group
573 ['foo]
574      @result{} [(quote foo)]
575 @end group
576 @end example
578   Other quoting constructs include @code{function} (@pxref{Anonymous
579 Functions}), which causes an anonymous lambda expression written in Lisp
580 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
581 only part of a list, while computing and substituting other parts.
583 @node Eval
584 @section Eval
586   Most often, forms are evaluated automatically, by virtue of their
587 occurrence in a program being run.  On rare occasions, you may need to
588 write code that evaluates a form that is computed at run time, such as
589 after reading a form from text being edited or getting one from a
590 property list.  On these occasions, use the @code{eval} function.
592   The functions and variables described in this section evaluate forms,
593 specify limits to the evaluation process, or record recently returned
594 values.  Loading a file also does evaluation (@pxref{Loading}).
596   It is generally cleaner and more flexible to store a function in a
597 data structure, and call it with @code{funcall} or @code{apply}, than
598 to store an expression in the data structure and evaluate it.  Using
599 functions provides the ability to pass information to them as
600 arguments.
602 @defun eval form
603 This is the basic function evaluating an expression.  It evaluates
604 @var{form} in the current environment and returns the result.  How the
605 evaluation proceeds depends on the type of the object (@pxref{Forms}).
607 Since @code{eval} is a function, the argument expression that appears
608 in a call to @code{eval} is evaluated twice: once as preparation before
609 @code{eval} is called, and again by the @code{eval} function itself.
610 Here is an example:
612 @example
613 @group
614 (setq foo 'bar)
615      @result{} bar
616 @end group
617 @group
618 (setq bar 'baz)
619      @result{} baz
620 ;; @r{Here @code{eval} receives argument @code{foo}}
621 (eval 'foo)
622      @result{} bar
623 ;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}
624 (eval foo)
625      @result{} baz
626 @end group
627 @end example
629 The number of currently active calls to @code{eval} is limited to
630 @code{max-lisp-eval-depth} (see below).
631 @end defun
633 @deffn Command eval-region start end &optional stream read-function
634 @anchor{Definition of eval-region}
635 This function evaluates the forms in the current buffer in the region
636 defined by the positions @var{start} and @var{end}.  It reads forms from
637 the region and calls @code{eval} on them until the end of the region is
638 reached, or until an error is signaled and not handled.
640 By default, @code{eval-region} does not produce any output.  However,
641 if @var{stream} is non-@code{nil}, any output produced by output
642 functions (@pxref{Output Functions}), as well as the values that
643 result from evaluating the expressions in the region are printed using
644 @var{stream}.  @xref{Output Streams}.
646 If @var{read-function} is non-@code{nil}, it should be a function,
647 which is used instead of @code{read} to read expressions one by one.
648 This function is called with one argument, the stream for reading
649 input.  You can also use the variable @code{load-read-function}
650 (@pxref{Definition of load-read-function,, How Programs Do Loading})
651 to specify this function, but it is more robust to use the
652 @var{read-function} argument.
654 @code{eval-region} does not move point.  It always returns @code{nil}.
655 @end deffn
657 @cindex evaluation of buffer contents
658 @deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
659 This is similar to @code{eval-region}, but the arguments provide
660 different optional features.  @code{eval-buffer} operates on the
661 entire accessible portion of buffer @var{buffer-or-name}.
662 @var{buffer-or-name} can be a buffer, a buffer name (a string), or
663 @code{nil} (or omitted), which means to use the current buffer.
664 @var{stream} is used as in @code{eval-region}, unless @var{stream} is
665 @code{nil} and @var{print} non-@code{nil}.  In that case, values that
666 result from evaluating the expressions are still discarded, but the
667 output of the output functions is printed in the echo area.
668 @var{filename} is the file name to use for @code{load-history}
669 (@pxref{Unloading}), and defaults to @code{buffer-file-name}
670 (@pxref{Buffer File Name}).  If @var{unibyte} is non-@code{nil},
671 @code{read} converts strings to unibyte whenever possible.
673 @findex eval-current-buffer
674 @code{eval-current-buffer} is an alias for this command.
675 @end deffn
677 @defvar max-lisp-eval-depth
678 @anchor{Definition of max-lisp-eval-depth}
679 This variable defines the maximum depth allowed in calls to @code{eval},
680 @code{apply}, and @code{funcall} before an error is signaled (with error
681 message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).
683 This limit, with the associated error when it is exceeded, is one way
684 Emacs Lisp avoids infinite recursion on an ill-defined function.  If
685 you increase the value of @code{max-lisp-eval-depth} too much, such
686 code can cause stack overflow instead.
687 @cindex Lisp nesting error
689 The depth limit counts internal uses of @code{eval}, @code{apply}, and
690 @code{funcall}, such as for calling the functions mentioned in Lisp
691 expressions, and recursive evaluation of function call arguments and
692 function body forms, as well as explicit calls in Lisp code.
694 The default value of this variable is 300.  If you set it to a value
695 less than 100, Lisp will reset it to 100 if the given value is reached.
696 Entry to the Lisp debugger increases the value, if there is little room
697 left, to make sure the debugger itself has room to execute.
699 @code{max-specpdl-size} provides another limit on nesting.
700 @xref{Definition of max-specpdl-size,, Local Variables}.
701 @end defvar
703 @defvar values
704 The value of this variable is a list of the values returned by all the
705 expressions that were read, evaluated, and printed from buffers
706 (including the minibuffer) by the standard Emacs commands which do
707 this.  (Note that this does @emph{not} include evaluation in
708 @samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in
709 @code{lisp-interaction-mode}.)  The elements are ordered most recent
710 first.
712 @example
713 @group
714 (setq x 1)
715      @result{} 1
716 @end group
717 @group
718 (list 'A (1+ 2) auto-save-default)
719      @result{} (A 3 t)
720 @end group
721 @group
722 values
723      @result{} ((A 3 t) 1 @dots{})
724 @end group
725 @end example
727 This variable is useful for referring back to values of forms recently
728 evaluated.  It is generally a bad idea to print the value of
729 @code{values} itself, since this may be very long.  Instead, examine
730 particular elements, like this:
732 @example
733 @group
734 ;; @r{Refer to the most recent evaluation result.}
735 (nth 0 values)
736      @result{} (A 3 t)
737 @end group
738 @group
739 ;; @r{That put a new element on,}
740 ;;   @r{so all elements move back one.}
741 (nth 1 values)
742      @result{} (A 3 t)
743 @end group
744 @group
745 ;; @r{This gets the element that was next-to-most-recent}
746 ;;   @r{before this example.}
747 (nth 3 values)
748      @result{} 1
749 @end group
750 @end example
751 @end defvar
753 @ignore
754    arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57
755 @end ignore