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