eval.texi 25.8 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1 2 3
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2001, 2002, 2003,
Glenn Morris's avatar
Glenn Morris committed
4
@c   2004, 2005, 2006, 2007, 2008, 2009  Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
5
@c See the file elisp.texi for copying conditions.
6
@setfilename ../../info/eval
Glenn Morris's avatar
Glenn Morris committed
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
@node Evaluation, Control Structures, Symbols, Top
@chapter Evaluation
@cindex evaluation
@cindex  interpreter
@cindex interpreter
@cindex value of expression

  The @dfn{evaluation} of expressions in Emacs Lisp is performed by the
@dfn{Lisp interpreter}---a program that receives a Lisp object as input
and computes its @dfn{value as an expression}.  How it does this depends
on the data type of the object, according to rules described in this
chapter.  The interpreter runs automatically to evaluate portions of
your program, but can also be called explicitly via the Lisp primitive
function @code{eval}.

@ifnottex
@menu
* Intro Eval::  Evaluation in the scheme of things.
* Forms::       How various sorts of objects are evaluated.
* Quoting::     Avoiding evaluation (to put constants in the program).
* Eval::        How to invoke the Lisp interpreter explicitly.
@end menu

@node Intro Eval
@section Introduction to Evaluation

33 34 35 36 37 38
  The Lisp interpreter, or evaluator, is the part of Emacs that
computes the value of an expression that is given to it.  When a
function written in Lisp is called, the evaluator computes the value
of the function by evaluating the expressions in the function body.
Thus, running any Lisp program really means running the Lisp
interpreter.
Glenn Morris's avatar
Glenn Morris committed
39 40
@end ifnottex

41
@cindex form
Glenn Morris's avatar
Glenn Morris committed
42 43
@cindex expression
  A Lisp object that is intended for evaluation is called an
44
@dfn{expression} or a @dfn{form}.  The fact that forms are data
Glenn Morris's avatar
Glenn Morris committed
45 46 47 48 49
objects and not merely text is one of the fundamental differences
between Lisp-like languages and typical programming languages.  Any
object can be evaluated, but in practice only numbers, symbols, lists
and strings are evaluated very often.

50 51 52 53 54 55 56 57
  In subsequent sections, we will describe the details of what
evaluation means for each kind of form.

  It is very common to read a Lisp form and then evaluate the form,
but reading and evaluation are separate activities, and either can be
performed alone.  Reading per se does not evaluate anything; it
converts the printed representation of a Lisp object to the object
itself.  It is up to the caller of @code{read} to specify whether this
Glenn Morris's avatar
Glenn Morris committed
58 59 60 61
object is a form to be evaluated, or serves some entirely different
purpose.  @xref{Input Functions}.

@cindex recursive evaluation
62 63 64 65 66 67 68 69 70 71
  Evaluation is a recursive process, and evaluating a form often
involves evaluating parts within that form.  For instance, when you
evaluate a @dfn{function call} form such as @code{(car x)}, Emacs
first evaluates the argument (the subform @code{x}).  After evaluating
the argument, Emacs @dfn{executes} the function (@code{car}), and if
the function is written in Lisp, execution works by evaluating the
@dfn{body} of the function.  (In this example, however, @code{car} is
not a Lisp function; it is a primitive function implemented in C.)
@xref{Functions}, for more information about functions and function
calls.
Glenn Morris's avatar
Glenn Morris committed
72 73

@cindex environment
74 75 76 77 78 79 80 81 82 83
  Evaluation takes place in a context called the @dfn{environment},
which consists of the current values and bindings of all Lisp
variables (@pxref{Variables}).@footnote{This definition of
``environment'' is specifically not intended to include all the data
that can affect the result of a program.}  Whenever a form refers to a
variable without creating a new binding for it, the variable evaluates
to the value given by the current environment.  Evaluating a form may
create a new environment for recursive evaluation, by binding
variables (@pxref{Local Variables}).  Such environments are temporary,
and vanish when the evaluation of the form is complete.
Glenn Morris's avatar
Glenn Morris committed
84 85

@cindex side effect
86 87 88
  Evaluating a form may also make changes that persist; these changes
are called @dfn{side effects}.  An example of a form that produces a
side effect is @code{(setq foo 1)}.
Glenn Morris's avatar
Glenn Morris committed
89

90 91 92 93 94 95 96
  Do not confuse evaluation with command key interpretation.  The
editor command loop translates keyboard input into a command (an
interactively callable function) using the active keymaps, and then
uses @code{call-interactively} to execute that command.  Executing the
command usually involves evaluation, if the command is written in
Lisp; however, this step is not considered a part of command key
interpretation.  @xref{Command Loop}.
Glenn Morris's avatar
Glenn Morris committed
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127

@node Forms
@section Kinds of Forms

  A Lisp object that is intended to be evaluated is called a @dfn{form}.
How Emacs evaluates a form depends on its data type.  Emacs has three
different kinds of form that are evaluated differently: symbols, lists,
and ``all other types.''  This section describes all three kinds, one by
one, starting with the ``all other types'' which are self-evaluating
forms.

@menu
* Self-Evaluating Forms::   Forms that evaluate to themselves.
* Symbol Forms::            Symbols evaluate as variables.
* Classifying Lists::       How to distinguish various sorts of list forms.
* Function Indirection::    When a symbol appears as the car of a list,
			      we find the real function via the symbol.
* Function Forms::          Forms that call functions.
* Macro Forms::             Forms that call macros.
* Special Forms::           "Special forms" are idiosyncratic primitives,
                              most of them extremely important.
* Autoloading::             Functions set up to load files
                              containing their real definitions.
@end menu

@node Self-Evaluating Forms
@subsection Self-Evaluating Forms
@cindex vector evaluation
@cindex literal evaluation
@cindex self-evaluating form

128 129 130 131 132 133 134
  A @dfn{self-evaluating form} is any form that is not a list or
symbol.  Self-evaluating forms evaluate to themselves: the result of
evaluation is the same object that was evaluated.  Thus, the number 25
evaluates to 25, and the string @code{"foo"} evaluates to the string
@code{"foo"}.  Likewise, evaluating a vector does not cause evaluation
of the elements of the vector---it returns the same vector with its
contents unchanged.
Glenn Morris's avatar
Glenn Morris committed
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233

@example
@group
'123               ; @r{A number, shown without evaluation.}
     @result{} 123
@end group
@group
123                ; @r{Evaluated as usual---result is the same.}
     @result{} 123
@end group
@group
(eval '123)        ; @r{Evaluated ``by hand''---result is the same.}
     @result{} 123
@end group
@group
(eval (eval '123)) ; @r{Evaluating twice changes nothing.}
     @result{} 123
@end group
@end example

  It is common to write numbers, characters, strings, and even vectors
in Lisp code, taking advantage of the fact that they self-evaluate.
However, it is quite unusual to do this for types that lack a read
syntax, because there's no way to write them textually.  It is possible
to construct Lisp expressions containing these types by means of a Lisp
program.  Here is an example:

@example
@group
;; @r{Build an expression containing a buffer object.}
(setq print-exp (list 'print (current-buffer)))
     @result{} (print #<buffer eval.texi>)
@end group
@group
;; @r{Evaluate it.}
(eval print-exp)
     @print{} #<buffer eval.texi>
     @result{} #<buffer eval.texi>
@end group
@end example

@node Symbol Forms
@subsection Symbol Forms
@cindex symbol evaluation

  When a symbol is evaluated, it is treated as a variable.  The result
is the variable's value, if it has one.  If it has none (if its value
cell is void), an error is signaled.  For more information on the use of
variables, see @ref{Variables}.

  In the following example, we set the value of a symbol with
@code{setq}.  Then we evaluate the symbol, and get back the value that
@code{setq} stored.

@example
@group
(setq a 123)
     @result{} 123
@end group
@group
(eval 'a)
     @result{} 123
@end group
@group
a
     @result{} 123
@end group
@end example

  The symbols @code{nil} and @code{t} are treated specially, so that the
value of @code{nil} is always @code{nil}, and the value of @code{t} is
always @code{t}; you cannot set or bind them to any other values.  Thus,
these two symbols act like self-evaluating forms, even though
@code{eval} treats them like any other symbol.  A symbol whose name
starts with @samp{:} also self-evaluates in the same way; likewise,
its value ordinarily cannot be changed.  @xref{Constant Variables}.

@node Classifying Lists
@subsection Classification of List Forms
@cindex list form evaluation

  A form that is a nonempty list is either a function call, a macro
call, or a special form, according to its first element.  These three
kinds of forms are evaluated in different ways, described below.  The
remaining list elements constitute the @dfn{arguments} for the function,
macro, or special form.

  The first step in evaluating a nonempty list is to examine its first
element.  This element alone determines what kind of form the list is
and how the rest of the list is to be processed.  The first element is
@emph{not} evaluated, as it would be in some Lisp dialects such as
Scheme.

@node Function Indirection
@subsection Symbol Function Indirection
@cindex symbol function indirection
@cindex indirection for functions
@cindex void function

234 235 236 237 238 239
  If the first element of the list is a symbol then evaluation
examines the symbol's function cell, and uses its contents instead of
the original symbol.  If the contents are another symbol, this
process, called @dfn{symbol function indirection}, is repeated until
it obtains a non-symbol.  @xref{Function Names}, for more information
about symbol function indirection.
Glenn Morris's avatar
Glenn Morris committed
240 241 242 243 244 245 246 247 248 249

  One possible consequence of this process is an infinite loop, in the
event that a symbol's function cell refers to the same symbol.  Or a
symbol may have a void function cell, in which case the subroutine
@code{symbol-function} signals a @code{void-function} error.  But if
neither of these things happens, we eventually obtain a non-symbol,
which ought to be a function or other suitable object.

@kindex invalid-function
  More precisely, we should now have a Lisp function (a lambda
250 251 252 253
expression), a byte-code function, a primitive function, a Lisp macro,
a special form, or an autoload object.  Each of these types is a case
described in one of the following sections.  If the object is not one
of these types, Emacs signals an @code{invalid-function} error.
Glenn Morris's avatar
Glenn Morris committed
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406

  The following example illustrates the symbol indirection process.  We
use @code{fset} to set the function cell of a symbol and
@code{symbol-function} to get the function cell contents
(@pxref{Function Cells}).  Specifically, we store the symbol @code{car}
into the function cell of @code{first}, and the symbol @code{first} into
the function cell of @code{erste}.

@smallexample
@group
;; @r{Build this function cell linkage:}
;;   -------------       -----        -------        -------
;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
;;   -------------       -----        -------        -------
@end group
@end smallexample

@smallexample
@group
(symbol-function 'car)
     @result{} #<subr car>
@end group
@group
(fset 'first 'car)
     @result{} car
@end group
@group
(fset 'erste 'first)
     @result{} first
@end group
@group
(erste '(1 2 3))   ; @r{Call the function referenced by @code{erste}.}
     @result{} 1
@end group
@end smallexample

  By contrast, the following example calls a function without any symbol
function indirection, because the first element is an anonymous Lisp
function, not a symbol.

@smallexample
@group
((lambda (arg) (erste arg))
 '(1 2 3))
     @result{} 1
@end group
@end smallexample

@noindent
Executing the function itself evaluates its body; this does involve
symbol function indirection when calling @code{erste}.

  The built-in function @code{indirect-function} provides an easy way to
perform symbol function indirection explicitly.

@c Emacs 19 feature
@defun indirect-function function &optional noerror
@anchor{Definition of indirect-function}
This function returns the meaning of @var{function} as a function.  If
@var{function} is a symbol, then it finds @var{function}'s function
definition and starts over with that value.  If @var{function} is not a
symbol, then it returns @var{function} itself.

This function signals a @code{void-function} error if the final symbol
is unbound and optional argument @var{noerror} is @code{nil} or
omitted.  Otherwise, if @var{noerror} is non-@code{nil}, it returns
@code{nil} if the final symbol is unbound.

It signals a @code{cyclic-function-indirection} error if there is a
loop in the chain of symbols.

Here is how you could define @code{indirect-function} in Lisp:

@smallexample
(defun indirect-function (function)
  (if (symbolp function)
      (indirect-function (symbol-function function))
    function))
@end smallexample
@end defun

@node Function Forms
@subsection Evaluation of Function Forms
@cindex function form evaluation
@cindex function call

  If the first element of a list being evaluated is a Lisp function
object, byte-code object or primitive function object, then that list is
a @dfn{function call}.  For example, here is a call to the function
@code{+}:

@example
(+ 1 x)
@end example

  The first step in evaluating a function call is to evaluate the
remaining elements of the list from left to right.  The results are the
actual argument values, one value for each list element.  The next step
is to call the function with this list of arguments, effectively using
the function @code{apply} (@pxref{Calling Functions}).  If the function
is written in Lisp, the arguments are used to bind the argument
variables of the function (@pxref{Lambda Expressions}); then the forms
in the function body are evaluated in order, and the value of the last
body form becomes the value of the function call.

@node Macro Forms
@subsection Lisp Macro Evaluation
@cindex macro call evaluation

  If the first element of a list being evaluated is a macro object, then
the list is a @dfn{macro call}.  When a macro call is evaluated, the
elements of the rest of the list are @emph{not} initially evaluated.
Instead, these elements themselves are used as the arguments of the
macro.  The macro definition computes a replacement form, called the
@dfn{expansion} of the macro, to be evaluated in place of the original
form.  The expansion may be any sort of form: a self-evaluating
constant, a symbol, or a list.  If the expansion is itself a macro call,
this process of expansion repeats until some other sort of form results.

  Ordinary evaluation of a macro call finishes by evaluating the
expansion.  However, the macro expansion is not necessarily evaluated
right away, or at all, because other programs also expand macro calls,
and they may or may not evaluate the expansions.

  Normally, the argument expressions are not evaluated as part of
computing the macro expansion, but instead appear as part of the
expansion, so they are computed when the expansion is evaluated.

  For example, given a macro defined as follows:

@example
@group
(defmacro cadr (x)
  (list 'car (list 'cdr x)))
@end group
@end example

@noindent
an expression such as @code{(cadr (assq 'handler list))} is a macro
call, and its expansion is:

@example
(car (cdr (assq 'handler list)))
@end example

@noindent
Note that the argument @code{(assq 'handler list)} appears in the
expansion.

@xref{Macros}, for a complete description of Emacs Lisp macros.

@node Special Forms
@subsection Special Forms
407 408
@cindex special forms
@cindex evaluation of special forms
Glenn Morris's avatar
Glenn Morris committed
409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691

  A @dfn{special form} is a primitive function specially marked so that
its arguments are not all evaluated.  Most special forms define control
structures or perform variable bindings---things which functions cannot
do.

  Each special form has its own rules for which arguments are evaluated
and which are used without evaluation.  Whether a particular argument is
evaluated may depend on the results of evaluating other arguments.

  Here is a list, in alphabetical order, of all of the special forms in
Emacs Lisp with a reference to where each is described.

@table @code
@item and
@pxref{Combining Conditions}

@item catch
@pxref{Catch and Throw}

@item cond
@pxref{Conditionals}

@item condition-case
@pxref{Handling Errors}

@item defconst
@pxref{Defining Variables}

@item defmacro
@pxref{Defining Macros}

@item defun
@pxref{Defining Functions}

@item defvar
@pxref{Defining Variables}

@item function
@pxref{Anonymous Functions}

@item if
@pxref{Conditionals}

@item interactive
@pxref{Interactive Call}

@item let
@itemx let*
@pxref{Local Variables}

@item or
@pxref{Combining Conditions}

@item prog1
@itemx prog2
@itemx progn
@pxref{Sequencing}

@item quote
@pxref{Quoting}

@item save-current-buffer
@pxref{Current Buffer}

@item save-excursion
@pxref{Excursions}

@item save-restriction
@pxref{Narrowing}

@item save-window-excursion
@pxref{Window Configurations}

@item setq
@pxref{Setting Variables}

@item setq-default
@pxref{Creating Buffer-Local}

@item track-mouse
@pxref{Mouse Tracking}

@item unwind-protect
@pxref{Nonlocal Exits}

@item while
@pxref{Iteration}

@item with-output-to-temp-buffer
@pxref{Temporary Displays}
@end table

@cindex CL note---special forms compared
@quotation
@b{Common Lisp note:} Here are some comparisons of special forms in
GNU Emacs Lisp and Common Lisp.  @code{setq}, @code{if}, and
@code{catch} are special forms in both Emacs Lisp and Common Lisp.
@code{defun} is a special form in Emacs Lisp, but a macro in Common
Lisp.  @code{save-excursion} is a special form in Emacs Lisp, but
doesn't exist in Common Lisp.  @code{throw} is a special form in
Common Lisp (because it must be able to throw multiple values), but it
is a function in Emacs Lisp (which doesn't have multiple
values).@refill
@end quotation

@node Autoloading
@subsection Autoloading

  The @dfn{autoload} feature allows you to call a function or macro
whose function definition has not yet been loaded into Emacs.  It
specifies which file contains the definition.  When an autoload object
appears as a symbol's function definition, calling that symbol as a
function automatically loads the specified file; then it calls the real
definition loaded from that file.  @xref{Autoload}.

@node Quoting
@section Quoting

  The special form @code{quote} returns its single argument, as written,
without evaluating it.  This provides a way to include constant symbols
and lists, which are not self-evaluating objects, in a program.  (It is
not necessary to quote self-evaluating objects such as numbers, strings,
and vectors.)

@defspec quote object
This special form returns @var{object}, without evaluating it.
@end defspec

@cindex @samp{'} for quoting
@cindex quoting using apostrophe
@cindex apostrophe for quoting
Because @code{quote} is used so often in programs, Lisp provides a
convenient read syntax for it.  An apostrophe character (@samp{'})
followed by a Lisp object (in read syntax) expands to a list whose first
element is @code{quote}, and whose second element is the object.  Thus,
the read syntax @code{'x} is an abbreviation for @code{(quote x)}.

Here are some examples of expressions that use @code{quote}:

@example
@group
(quote (+ 1 2))
     @result{} (+ 1 2)
@end group
@group
(quote foo)
     @result{} foo
@end group
@group
'foo
     @result{} foo
@end group
@group
''foo
     @result{} (quote foo)
@end group
@group
'(quote foo)
     @result{} (quote foo)
@end group
@group
['foo]
     @result{} [(quote foo)]
@end group
@end example

  Other quoting constructs include @code{function} (@pxref{Anonymous
Functions}), which causes an anonymous lambda expression written in Lisp
to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
only part of a list, while computing and substituting other parts.

@node Eval
@section Eval

  Most often, forms are evaluated automatically, by virtue of their
occurrence in a program being run.  On rare occasions, you may need to
write code that evaluates a form that is computed at run time, such as
after reading a form from text being edited or getting one from a
property list.  On these occasions, use the @code{eval} function.

  The functions and variables described in this section evaluate forms,
specify limits to the evaluation process, or record recently returned
values.  Loading a file also does evaluation (@pxref{Loading}).

  It is generally cleaner and more flexible to store a function in a
data structure, and call it with @code{funcall} or @code{apply}, than
to store an expression in the data structure and evaluate it.  Using
functions provides the ability to pass information to them as
arguments.

@defun eval form
This is the basic function evaluating an expression.  It evaluates
@var{form} in the current environment and returns the result.  How the
evaluation proceeds depends on the type of the object (@pxref{Forms}).

Since @code{eval} is a function, the argument expression that appears
in a call to @code{eval} is evaluated twice: once as preparation before
@code{eval} is called, and again by the @code{eval} function itself.
Here is an example:

@example
@group
(setq foo 'bar)
     @result{} bar
@end group
@group
(setq bar 'baz)
     @result{} baz
;; @r{Here @code{eval} receives argument @code{foo}}
(eval 'foo)
     @result{} bar
;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}
(eval foo)
     @result{} baz
@end group
@end example

The number of currently active calls to @code{eval} is limited to
@code{max-lisp-eval-depth} (see below).
@end defun

@deffn Command eval-region start end &optional stream read-function
@anchor{Definition of eval-region}
This function evaluates the forms in the current buffer in the region
defined by the positions @var{start} and @var{end}.  It reads forms from
the region and calls @code{eval} on them until the end of the region is
reached, or until an error is signaled and not handled.

By default, @code{eval-region} does not produce any output.  However,
if @var{stream} is non-@code{nil}, any output produced by output
functions (@pxref{Output Functions}), as well as the values that
result from evaluating the expressions in the region are printed using
@var{stream}.  @xref{Output Streams}.

If @var{read-function} is non-@code{nil}, it should be a function,
which is used instead of @code{read} to read expressions one by one.
This function is called with one argument, the stream for reading
input.  You can also use the variable @code{load-read-function}
(@pxref{Definition of load-read-function,, How Programs Do Loading})
to specify this function, but it is more robust to use the
@var{read-function} argument.

@code{eval-region} does not move point.  It always returns @code{nil}.
@end deffn

@cindex evaluation of buffer contents
@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
This is similar to @code{eval-region}, but the arguments provide
different optional features.  @code{eval-buffer} operates on the
entire accessible portion of buffer @var{buffer-or-name}.
@var{buffer-or-name} can be a buffer, a buffer name (a string), or
@code{nil} (or omitted), which means to use the current buffer.
@var{stream} is used as in @code{eval-region}, unless @var{stream} is
@code{nil} and @var{print} non-@code{nil}.  In that case, values that
result from evaluating the expressions are still discarded, but the
output of the output functions is printed in the echo area.
@var{filename} is the file name to use for @code{load-history}
(@pxref{Unloading}), and defaults to @code{buffer-file-name}
(@pxref{Buffer File Name}).  If @var{unibyte} is non-@code{nil},
@code{read} converts strings to unibyte whenever possible.

@findex eval-current-buffer
@code{eval-current-buffer} is an alias for this command.
@end deffn

@defvar max-lisp-eval-depth
@anchor{Definition of max-lisp-eval-depth}
This variable defines the maximum depth allowed in calls to @code{eval},
@code{apply}, and @code{funcall} before an error is signaled (with error
message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).

This limit, with the associated error when it is exceeded, is one way
Emacs Lisp avoids infinite recursion on an ill-defined function.  If
you increase the value of @code{max-lisp-eval-depth} too much, such
code can cause stack overflow instead.
@cindex Lisp nesting error

The depth limit counts internal uses of @code{eval}, @code{apply}, and
@code{funcall}, such as for calling the functions mentioned in Lisp
expressions, and recursive evaluation of function call arguments and
function body forms, as well as explicit calls in Lisp code.

692 693 694 695 696
The default value of this variable is 400.  If you set it to a value
less than 100, Lisp will reset it to 100 if the given value is
reached.  Entry to the Lisp debugger increases the value, if there is
little room left, to make sure the debugger itself has room to
execute.
Glenn Morris's avatar
Glenn Morris committed
697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754

@code{max-specpdl-size} provides another limit on nesting.
@xref{Definition of max-specpdl-size,, Local Variables}.
@end defvar

@defvar values
The value of this variable is a list of the values returned by all the
expressions that were read, evaluated, and printed from buffers
(including the minibuffer) by the standard Emacs commands which do
this.  (Note that this does @emph{not} include evaluation in
@samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in
@code{lisp-interaction-mode}.)  The elements are ordered most recent
first.

@example
@group
(setq x 1)
     @result{} 1
@end group
@group
(list 'A (1+ 2) auto-save-default)
     @result{} (A 3 t)
@end group
@group
values
     @result{} ((A 3 t) 1 @dots{})
@end group
@end example

This variable is useful for referring back to values of forms recently
evaluated.  It is generally a bad idea to print the value of
@code{values} itself, since this may be very long.  Instead, examine
particular elements, like this:

@example
@group
;; @r{Refer to the most recent evaluation result.}
(nth 0 values)
     @result{} (A 3 t)
@end group
@group
;; @r{That put a new element on,}
;;   @r{so all elements move back one.}
(nth 1 values)
     @result{} (A 3 t)
@end group
@group
;; @r{This gets the element that was next-to-most-recent}
;;   @r{before this example.}
(nth 3 values)
     @result{} 1
@end group
@end example
@end defvar

@ignore
   arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57
@end ignore