| 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 |
| 12 | |
| 13 | The @dfn{evaluation} of expressions in Emacs Lisp is performed by the |
| 14 | @dfn{Lisp interpreter}---a program that receives a Lisp object as input |
| 15 | and computes its @dfn{value as an expression}. How it does this depends |
| 16 | on the data type of the object, according to rules described in this |
| 17 | chapter. The interpreter runs automatically to evaluate portions of |
| 18 | your program, but can also be called explicitly via the Lisp primitive |
| 19 | function @code{eval}. |
| 20 | |
| 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 |
| 28 | |
| 29 | @node Intro Eval |
| 30 | @section Introduction to Evaluation |
| 31 | |
| 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. |
| 37 | |
| 38 | How the evaluator handles an object depends primarily on the data |
| 39 | type of the object. |
| 40 | @end ifnottex |
| 41 | |
| 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. |
| 50 | |
| 51 | It is very common to read a Lisp expression and then evaluate the |
| 52 | expression, but reading and evaluation are separate activities, and |
| 53 | either can be performed alone. Reading per se does not evaluate |
| 54 | anything; it converts the printed representation of a Lisp object to the |
| 55 | object itself. It is up to the caller of @code{read} whether this |
| 56 | object is a form to be evaluated, or serves some entirely different |
| 57 | purpose. @xref{Input Functions}. |
| 58 | |
| 59 | Do not confuse evaluation with command key interpretation. The |
| 60 | editor command loop translates keyboard input into a command (an |
| 61 | interactively callable function) using the active keymaps, and then |
| 62 | uses @code{call-interactively} to invoke the command. The execution of |
| 63 | the command itself involves evaluation if the command is written in |
| 64 | Lisp, but that is not a part of command key interpretation itself. |
| 65 | @xref{Command Loop}. |
| 66 | |
| 67 | @cindex recursive evaluation |
| 68 | Evaluation is a recursive process. That is, evaluation of a form may |
| 69 | call @code{eval} to evaluate parts of the form. For example, evaluation |
| 70 | of a function call first evaluates each argument of the function call, |
| 71 | and then evaluates each form in the function body. Consider evaluation |
| 72 | of the form @code{(car x)}: the subform @code{x} must first be evaluated |
| 73 | recursively, so that its value can be passed as an argument to the |
| 74 | function @code{car}. |
| 75 | |
| 76 | Evaluation of a function call ultimately calls the function specified |
| 77 | in it. @xref{Functions}. The execution of the function may itself work |
| 78 | by evaluating the function definition; or the function may be a Lisp |
| 79 | primitive implemented in C, or it may be a byte-compiled function |
| 80 | (@pxref{Byte Compilation}). |
| 81 | |
| 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}. |
| 90 | |
| 91 | @cindex side effect |
| 92 | Evaluation of a form may create new environments for recursive |
| 93 | evaluation by binding variables (@pxref{Local Variables}). These |
| 94 | environments are temporary and vanish by the time evaluation of the form |
| 95 | is complete. The form may also make changes that persist; these changes |
| 96 | are called @dfn{side effects}. An example of a form that produces side |
| 97 | effects is @code{(setq foo 1)}. |
| 98 | |
| 99 | The details of what evaluation means for each kind of form are |
| 100 | described below (@pxref{Forms}). |
| 101 | |
| 102 | @node Forms |
| 103 | @section Kinds of Forms |
| 104 | |
| 105 | A Lisp object that is intended to be evaluated is called a @dfn{form}. |
| 106 | How Emacs evaluates a form depends on its data type. Emacs has three |
| 107 | different kinds of form that are evaluated differently: symbols, lists, |
| 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. |
| 111 | |
| 112 | @menu |
| 113 | * Self-Evaluating Forms:: Forms that evaluate to themselves. |
| 114 | * Symbol Forms:: Symbols evaluate as variables. |
| 115 | * Classifying Lists:: How to distinguish various sorts of list forms. |
| 116 | * Function Indirection:: When a symbol appears as the car of a list, |
| 117 | we find the real function via the symbol. |
| 118 | * Function Forms:: Forms that call functions. |
| 119 | * Macro Forms:: Forms that call macros. |
| 120 | * Special Forms:: ``Special forms'' are idiosyncratic primitives, |
| 121 | most of them extremely important. |
| 122 | * Autoloading:: Functions set up to load files |
| 123 | containing their real definitions. |
| 124 | @end menu |
| 125 | |
| 126 | @node Self-Evaluating Forms |
| 127 | @subsection Self-Evaluating Forms |
| 128 | @cindex vector evaluation |
| 129 | @cindex literal evaluation |
| 130 | @cindex self-evaluating form |
| 131 | |
| 132 | A @dfn{self-evaluating form} is any form that is not a list or symbol. |
| 133 | Self-evaluating forms evaluate to themselves: the result of evaluation |
| 134 | is the same object that was evaluated. Thus, the number 25 evaluates to |
| 135 | 25, and the string @code{"foo"} evaluates to the string @code{"foo"}. |
| 136 | Likewise, evaluation of a vector does not cause evaluation of the |
| 137 | elements of the vector---it returns the same vector with its contents |
| 138 | unchanged. |
| 139 | |
| 140 | @example |
| 141 | @group |
| 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 |
| 158 | |
| 159 | It is common to write numbers, characters, strings, and even vectors |
| 160 | in Lisp code, taking advantage of the fact that they self-evaluate. |
| 161 | However, it is quite unusual to do this for types that lack a read |
| 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: |
| 165 | |
| 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 |
| 179 | |
| 180 | @node Symbol Forms |
| 181 | @subsection Symbol Forms |
| 182 | @cindex symbol evaluation |
| 183 | |
| 184 | When a symbol is evaluated, it is treated as a variable. The result |
| 185 | is the variable's value, if it has one. If it has none (if its value |
| 186 | cell is void), an error is signaled. For more information on the use of |
| 187 | variables, see @ref{Variables}. |
| 188 | |
| 189 | In the following example, we set the value of a symbol with |
| 190 | @code{setq}. Then we evaluate the symbol, and get back the value that |
| 191 | @code{setq} stored. |
| 192 | |
| 193 | @example |
| 194 | @group |
| 195 | (setq a 123) |
| 196 | @result{} 123 |
| 197 | @end group |
| 198 | @group |
| 199 | (eval 'a) |
| 200 | @result{} 123 |
| 201 | @end group |
| 202 | @group |
| 203 | a |
| 204 | @result{} 123 |
| 205 | @end group |
| 206 | @end example |
| 207 | |
| 208 | The symbols @code{nil} and @code{t} are treated specially, so that the |
| 209 | value of @code{nil} is always @code{nil}, and the value of @code{t} is |
| 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}. |
| 215 | |
| 216 | @node Classifying Lists |
| 217 | @subsection Classification of List Forms |
| 218 | @cindex list form evaluation |
| 219 | |
| 220 | A form that is a nonempty list is either a function call, a macro |
| 221 | call, or a special form, according to its first element. These three |
| 222 | kinds of forms are evaluated in different ways, described below. The |
| 223 | remaining list elements constitute the @dfn{arguments} for the function, |
| 224 | macro, or special form. |
| 225 | |
| 226 | The first step in evaluating a nonempty list is to examine its first |
| 227 | element. This element alone determines what kind of form the list is |
| 228 | and how the rest of the list is to be processed. The first element is |
| 229 | @emph{not} evaluated, as it would be in some Lisp dialects such as |
| 230 | Scheme. |
| 231 | |
| 232 | @node Function Indirection |
| 233 | @subsection Symbol Function Indirection |
| 234 | @cindex symbol function indirection |
| 235 | @cindex indirection |
| 236 | @cindex void function |
| 237 | |
| 238 | If the first element of the list is a symbol then evaluation examines |
| 239 | the symbol's function cell, and uses its contents instead of the |
| 240 | original symbol. If the contents are another symbol, this process, |
| 241 | called @dfn{symbol function indirection}, is repeated until it obtains a |
| 242 | non-symbol. @xref{Function Names}, for more information about using a |
| 243 | symbol as a name for a function stored in the function cell of the |
| 244 | symbol. |
| 245 | |
| 246 | One possible consequence of this process is an infinite loop, in the |
| 247 | event that a symbol's function cell refers to the same symbol. Or a |
| 248 | symbol may have a void function cell, in which case the subroutine |
| 249 | @code{symbol-function} signals a @code{void-function} error. But if |
| 250 | neither of these things happens, we eventually obtain a non-symbol, |
| 251 | which ought to be a function or other suitable object. |
| 252 | |
| 253 | @kindex invalid-function |
| 254 | @cindex invalid function |
| 255 | More precisely, we should now have a Lisp function (a lambda |
| 256 | expression), a byte-code function, a primitive function, a Lisp macro, a |
| 257 | special form, or an autoload object. Each of these types is a case |
| 258 | described in one of the following sections. If the object is not one of |
| 259 | these types, the error @code{invalid-function} is signaled. |
| 260 | |
| 261 | The following example illustrates the symbol indirection process. We |
| 262 | use @code{fset} to set the function cell of a symbol and |
| 263 | @code{symbol-function} to get the function cell contents |
| 264 | (@pxref{Function Cells}). Specifically, we store the symbol @code{car} |
| 265 | into the function cell of @code{first}, and the symbol @code{first} into |
| 266 | the function cell of @code{erste}. |
| 267 | |
| 268 | @smallexample |
| 269 | @group |
| 270 | ;; @r{Build this function cell linkage:} |
| 271 | ;; ------------- ----- ------- ------- |
| 272 | ;; | #<subr car> | <-- | car | <-- | first | <-- | erste | |
| 273 | ;; ------------- ----- ------- ------- |
| 274 | @end group |
| 275 | @end smallexample |
| 276 | |
| 277 | @smallexample |
| 278 | @group |
| 279 | (symbol-function 'car) |
| 280 | @result{} #<subr car> |
| 281 | @end group |
| 282 | @group |
| 283 | (fset 'first 'car) |
| 284 | @result{} car |
| 285 | @end group |
| 286 | @group |
| 287 | (fset 'erste 'first) |
| 288 | @result{} first |
| 289 | @end group |
| 290 | @group |
| 291 | (erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.} |
| 292 | @result{} 1 |
| 293 | @end group |
| 294 | @end smallexample |
| 295 | |
| 296 | By contrast, the following example calls a function without any symbol |
| 297 | function indirection, because the first element is an anonymous Lisp |
| 298 | function, not a symbol. |
| 299 | |
| 300 | @smallexample |
| 301 | @group |
| 302 | ((lambda (arg) (erste arg)) |
| 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 |
| 317 | This function returns the meaning of @var{function} as a function. If |
| 318 | @var{function} is a symbol, then it finds @var{function}'s function |
| 319 | definition and starts over with that value. If @var{function} is not a |
| 320 | symbol, then it returns @var{function} itself. |
| 321 | |
| 322 | Here is how you could define @code{indirect-function} in Lisp: |
| 323 | |
| 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 |
| 331 | |
| 332 | @node Function Forms |
| 333 | @subsection Evaluation of Function Forms |
| 334 | @cindex function form evaluation |
| 335 | @cindex function call |
| 336 | |
| 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{+}: |
| 341 | |
| 342 | @example |
| 343 | (+ 1 x) |
| 344 | @end example |
| 345 | |
| 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. |
| 355 | |
| 356 | @node Macro Forms |
| 357 | @subsection Lisp Macro Evaluation |
| 358 | @cindex macro call evaluation |
| 359 | |
| 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. |
| 369 | |
| 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. |
| 374 | |
| 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. |
| 378 | |
| 379 | For example, given a macro defined as follows: |
| 380 | |
| 381 | @example |
| 382 | @group |
| 383 | (defmacro cadr (x) |
| 384 | (list 'car (list 'cdr x))) |
| 385 | @end group |
| 386 | @end example |
| 387 | |
| 388 | @noindent |
| 389 | an expression such as @code{(cadr (assq 'handler list))} is a macro |
| 390 | call, and its expansion is: |
| 391 | |
| 392 | @example |
| 393 | (car (cdr (assq 'handler list))) |
| 394 | @end example |
| 395 | |
| 396 | @noindent |
| 397 | Note that the argument @code{(assq 'handler list)} appears in the |
| 398 | expansion. |
| 399 | |
| 400 | @xref{Macros}, for a complete description of Emacs Lisp macros. |
| 401 | |
| 402 | @node Special Forms |
| 403 | @subsection Special Forms |
| 404 | @cindex special form evaluation |
| 405 | |
| 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 |
| 409 | do. |
| 410 | |
| 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. |
| 414 | |
| 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. |
| 417 | |
| 418 | @table @code |
| 419 | @item and |
| 420 | @pxref{Combining Conditions} |
| 421 | |
| 422 | @item catch |
| 423 | @pxref{Catch and Throw} |
| 424 | |
| 425 | @item cond |
| 426 | @pxref{Conditionals} |
| 427 | |
| 428 | @item condition-case |
| 429 | @pxref{Handling Errors} |
| 430 | |
| 431 | @item defconst |
| 432 | @pxref{Defining Variables} |
| 433 | |
| 434 | @item defmacro |
| 435 | @pxref{Defining Macros} |
| 436 | |
| 437 | @item defun |
| 438 | @pxref{Defining Functions} |
| 439 | |
| 440 | @item defvar |
| 441 | @pxref{Defining Variables} |
| 442 | |
| 443 | @item function |
| 444 | @pxref{Anonymous Functions} |
| 445 | |
| 446 | @item if |
| 447 | @pxref{Conditionals} |
| 448 | |
| 449 | @item interactive |
| 450 | @pxref{Interactive Call} |
| 451 | |
| 452 | @item let |
| 453 | @itemx let* |
| 454 | @pxref{Local Variables} |
| 455 | |
| 456 | @item or |
| 457 | @pxref{Combining Conditions} |
| 458 | |
| 459 | @item prog1 |
| 460 | @itemx prog2 |
| 461 | @itemx progn |
| 462 | @pxref{Sequencing} |
| 463 | |
| 464 | @item quote |
| 465 | @pxref{Quoting} |
| 466 | |
| 467 | @item save-current-buffer |
| 468 | @pxref{Current Buffer} |
| 469 | |
| 470 | @item save-excursion |
| 471 | @pxref{Excursions} |
| 472 | |
| 473 | @item save-restriction |
| 474 | @pxref{Narrowing} |
| 475 | |
| 476 | @item save-window-excursion |
| 477 | @pxref{Window Configurations} |
| 478 | |
| 479 | @item setq |
| 480 | @pxref{Setting Variables} |
| 481 | |
| 482 | @item setq-default |
| 483 | @pxref{Creating Buffer-Local} |
| 484 | |
| 485 | @item track-mouse |
| 486 | @pxref{Mouse Tracking} |
| 487 | |
| 488 | @item unwind-protect |
| 489 | @pxref{Nonlocal Exits} |
| 490 | |
| 491 | @item while |
| 492 | @pxref{Iteration} |
| 493 | |
| 494 | @item with-output-to-temp-buffer |
| 495 | @pxref{Temporary Displays} |
| 496 | @end table |
| 497 | |
| 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 |
| 510 | |
| 511 | @node Autoloading |
| 512 | @subsection Autoloading |
| 513 | |
| 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}. |
| 520 | |
| 521 | @node Quoting |
| 522 | @section Quoting |
| 523 | @cindex quoting |
| 524 | |
| 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.) |
| 530 | |
| 531 | @defspec quote object |
| 532 | This special form returns @var{object}, without evaluating it. |
| 533 | @end defspec |
| 534 | |
| 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)}. |
| 543 | |
| 544 | Here are some examples of expressions that use @code{quote}: |
| 545 | |
| 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 |
| 572 | |
| 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. |
| 577 | |
| 578 | @node Eval |
| 579 | @section Eval |
| 580 | |
| 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. |
| 586 | |
| 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}). |
| 590 | |
| 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. |
| 596 | |
| 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}). |
| 601 | |
| 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: |
| 606 | |
| 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 |
| 623 | |
| 624 | The number of currently active calls to @code{eval} is limited to |
| 625 | @code{max-lisp-eval-depth} (see below). |
| 626 | @end defun |
| 627 | |
| 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. |
| 633 | |
| 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}. |
| 637 | |
| 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. |
| 644 | |
| 645 | @code{eval-region} always returns @code{nil}. |
| 646 | @end deffn |
| 647 | |
| 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 |
| 653 | |
| 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 |
| 661 | |
| 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. |
| 666 | |
| 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. |
| 671 | |
| 672 | @code{max-specpdl-size} provides another limit on nesting. |
| 673 | @xref{Local Variables}. |
| 674 | @end defvar |
| 675 | |
| 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. |
| 681 | |
| 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 |
| 696 | |
| 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: |
| 701 | |
| 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 |