| 1 | @c -*-texinfo-*- |
| 2 | @c This is part of the GNU Emacs Lisp Reference Manual. |
| 3 | @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. |
| 4 | @c See the file elisp.texi for copying conditions. |
| 5 | @setfilename ../info/macros |
| 6 | @node Macros, Customization, Functions, Top |
| 7 | @chapter Macros |
| 8 | @cindex macros |
| 9 | |
| 10 | @dfn{Macros} enable you to define new control constructs and other |
| 11 | language features. A macro is defined much like a function, but instead |
| 12 | of telling how to compute a value, it tells how to compute another Lisp |
| 13 | expression which will in turn compute the value. We call this |
| 14 | expression the @dfn{expansion} of the macro. |
| 15 | |
| 16 | Macros can do this because they operate on the unevaluated expressions |
| 17 | for the arguments, not on the argument values as functions do. They can |
| 18 | therefore construct an expansion containing these argument expressions |
| 19 | or parts of them. |
| 20 | |
| 21 | If you are using a macro to do something an ordinary function could |
| 22 | do, just for the sake of speed, consider using an inline function |
| 23 | instead. @xref{Inline Functions}. |
| 24 | |
| 25 | @menu |
| 26 | * Simple Macro:: A basic example. |
| 27 | * Expansion:: How, when and why macros are expanded. |
| 28 | * Compiling Macros:: How macros are expanded by the compiler. |
| 29 | * Defining Macros:: How to write a macro definition. |
| 30 | * Backquote:: Easier construction of list structure. |
| 31 | * Problems with Macros:: Don't evaluate the macro arguments too many times. |
| 32 | Don't hide the user's variables. |
| 33 | @end menu |
| 34 | |
| 35 | @node Simple Macro |
| 36 | @section A Simple Example of a Macro |
| 37 | |
| 38 | Suppose we would like to define a Lisp construct to increment a |
| 39 | variable value, much like the @code{++} operator in C. We would like to |
| 40 | write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}. |
| 41 | Here's a macro definition that does the job: |
| 42 | |
| 43 | @findex inc |
| 44 | @example |
| 45 | @group |
| 46 | (defmacro inc (var) |
| 47 | (list 'setq var (list '1+ var))) |
| 48 | @end group |
| 49 | @end example |
| 50 | |
| 51 | When this is called with @code{(inc x)}, the argument @var{var} is the |
| 52 | symbol @code{x}---@emph{not} the @emph{value} of @code{x}, as it would |
| 53 | be in a function. The body of the macro uses this to construct the |
| 54 | expansion, which is @code{(setq x (1+ x))}. Once the macro definition |
| 55 | returns this expansion, Lisp proceeds to evaluate it, thus incrementing |
| 56 | @code{x}. |
| 57 | |
| 58 | @node Expansion |
| 59 | @section Expansion of a Macro Call |
| 60 | @cindex expansion of macros |
| 61 | @cindex macro call |
| 62 | |
| 63 | A macro call looks just like a function call in that it is a list which |
| 64 | starts with the name of the macro. The rest of the elements of the list |
| 65 | are the arguments of the macro. |
| 66 | |
| 67 | Evaluation of the macro call begins like evaluation of a function call |
| 68 | except for one crucial difference: the macro arguments are the actual |
| 69 | expressions appearing in the macro call. They are not evaluated before |
| 70 | they are given to the macro definition. By contrast, the arguments of a |
| 71 | function are results of evaluating the elements of the function call |
| 72 | list. |
| 73 | |
| 74 | Having obtained the arguments, Lisp invokes the macro definition just |
| 75 | as a function is invoked. The argument variables of the macro are bound |
| 76 | to the argument values from the macro call, or to a list of them in the |
| 77 | case of a @code{&rest} argument. And the macro body executes and |
| 78 | returns its value just as a function body does. |
| 79 | |
| 80 | The second crucial difference between macros and functions is that the |
| 81 | value returned by the macro body is not the value of the macro call. |
| 82 | Instead, it is an alternate expression for computing that value, also |
| 83 | known as the @dfn{expansion} of the macro. The Lisp interpreter |
| 84 | proceeds to evaluate the expansion as soon as it comes back from the |
| 85 | macro. |
| 86 | |
| 87 | Since the expansion is evaluated in the normal manner, it may contain |
| 88 | calls to other macros. It may even be a call to the same macro, though |
| 89 | this is unusual. |
| 90 | |
| 91 | You can see the expansion of a given macro call by calling |
| 92 | @code{macroexpand}. |
| 93 | |
| 94 | @defun macroexpand form &optional environment |
| 95 | @cindex macro expansion |
| 96 | This function expands @var{form}, if it is a macro call. If the result |
| 97 | is another macro call, it is expanded in turn, until something which is |
| 98 | not a macro call results. That is the value returned by |
| 99 | @code{macroexpand}. If @var{form} is not a macro call to begin with, it |
| 100 | is returned as given. |
| 101 | |
| 102 | Note that @code{macroexpand} does not look at the subexpressions of |
| 103 | @var{form} (although some macro definitions may do so). Even if they |
| 104 | are macro calls themselves, @code{macroexpand} does not expand them. |
| 105 | |
| 106 | The function @code{macroexpand} does not expand calls to inline functions. |
| 107 | Normally there is no need for that, since a call to an inline function is |
| 108 | no harder to understand than a call to an ordinary function. |
| 109 | |
| 110 | If @var{environment} is provided, it specifies an alist of macro |
| 111 | definitions that shadow the currently defined macros. Byte compilation |
| 112 | uses this feature. |
| 113 | |
| 114 | @smallexample |
| 115 | @group |
| 116 | (defmacro inc (var) |
| 117 | (list 'setq var (list '1+ var))) |
| 118 | @result{} inc |
| 119 | @end group |
| 120 | |
| 121 | @group |
| 122 | (macroexpand '(inc r)) |
| 123 | @result{} (setq r (1+ r)) |
| 124 | @end group |
| 125 | |
| 126 | @group |
| 127 | (defmacro inc2 (var1 var2) |
| 128 | (list 'progn (list 'inc var1) (list 'inc var2))) |
| 129 | @result{} inc2 |
| 130 | @end group |
| 131 | |
| 132 | @group |
| 133 | (macroexpand '(inc2 r s)) |
| 134 | @result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.} |
| 135 | @end group |
| 136 | @end smallexample |
| 137 | @end defun |
| 138 | |
| 139 | @node Compiling Macros |
| 140 | @section Macros and Byte Compilation |
| 141 | @cindex byte-compiling macros |
| 142 | |
| 143 | You might ask why we take the trouble to compute an expansion for a |
| 144 | macro and then evaluate the expansion. Why not have the macro body |
| 145 | produce the desired results directly? The reason has to do with |
| 146 | compilation. |
| 147 | |
| 148 | When a macro call appears in a Lisp program being compiled, the Lisp |
| 149 | compiler calls the macro definition just as the interpreter would, and |
| 150 | receives an expansion. But instead of evaluating this expansion, it |
| 151 | compiles the expansion as if it had appeared directly in the program. |
| 152 | As a result, the compiled code produces the value and side effects |
| 153 | intended for the macro, but executes at full compiled speed. This would |
| 154 | not work if the macro body computed the value and side effects |
| 155 | itself---they would be computed at compile time, which is not useful. |
| 156 | |
| 157 | In order for compilation of macro calls to work, the macros must |
| 158 | already be defined in Lisp when the calls to them are compiled. The |
| 159 | compiler has a special feature to help you do this: if a file being |
| 160 | compiled contains a @code{defmacro} form, the macro is defined |
| 161 | temporarily for the rest of the compilation of that file. To make this |
| 162 | feature work, you must put the @code{defmacro} in the same file where it |
| 163 | is used, and before its first use. |
| 164 | |
| 165 | Byte-compiling a file executes any @code{require} calls at top-level |
| 166 | in the file. This is in case the file needs the required packages for |
| 167 | proper compilation. One way to ensure that necessary macro definitions |
| 168 | are available during compilation is to require the files that define |
| 169 | them (@pxref{Named Features}). To avoid loading the macro definition files |
| 170 | when someone @emph{runs} the compiled program, write |
| 171 | @code{eval-when-compile} around the @code{require} calls (@pxref{Eval |
| 172 | During Compile}). |
| 173 | |
| 174 | @node Defining Macros |
| 175 | @section Defining Macros |
| 176 | |
| 177 | A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should |
| 178 | be a function; expansion of the macro works by applying the function |
| 179 | (with @code{apply}) to the list of unevaluated argument-expressions |
| 180 | from the macro call. |
| 181 | |
| 182 | It is possible to use an anonymous Lisp macro just like an anonymous |
| 183 | function, but this is never done, because it does not make sense to pass |
| 184 | an anonymous macro to functionals such as @code{mapcar}. In practice, |
| 185 | all Lisp macros have names, and they are usually defined with the |
| 186 | special form @code{defmacro}. |
| 187 | |
| 188 | @defspec defmacro name argument-list body-forms@dots{} |
| 189 | @code{defmacro} defines the symbol @var{name} as a macro that looks |
| 190 | like this: |
| 191 | |
| 192 | @example |
| 193 | (macro lambda @var{argument-list} . @var{body-forms}) |
| 194 | @end example |
| 195 | |
| 196 | (Note that the @sc{cdr} of this list is a function---a lambda expression.) |
| 197 | This macro object is stored in the function cell of @var{name}. The |
| 198 | value returned by evaluating the @code{defmacro} form is @var{name}, but |
| 199 | usually we ignore this value. |
| 200 | |
| 201 | The shape and meaning of @var{argument-list} is the same as in a |
| 202 | function, and the keywords @code{&rest} and @code{&optional} may be used |
| 203 | (@pxref{Argument List}). Macros may have a documentation string, but |
| 204 | any @code{interactive} declaration is ignored since macros cannot be |
| 205 | called interactively. |
| 206 | @end defspec |
| 207 | |
| 208 | @node Backquote |
| 209 | @section Backquote |
| 210 | @cindex backquote (list substitution) |
| 211 | @cindex ` (list substitution) |
| 212 | @findex ` |
| 213 | |
| 214 | Macros often need to construct large list structures from a mixture of |
| 215 | constants and nonconstant parts. To make this easier, use the @samp{`} |
| 216 | syntax (usually called @dfn{backquote}). |
| 217 | |
| 218 | Backquote allows you to quote a list, but selectively evaluate |
| 219 | elements of that list. In the simplest case, it is identical to the |
| 220 | special form @code{quote} (@pxref{Quoting}). For example, these |
| 221 | two forms yield identical results: |
| 222 | |
| 223 | @example |
| 224 | @group |
| 225 | `(a list of (+ 2 3) elements) |
| 226 | @result{} (a list of (+ 2 3) elements) |
| 227 | @end group |
| 228 | @group |
| 229 | '(a list of (+ 2 3) elements) |
| 230 | @result{} (a list of (+ 2 3) elements) |
| 231 | @end group |
| 232 | @end example |
| 233 | |
| 234 | @findex , @r{(with Backquote)} |
| 235 | The special marker @samp{,} inside of the argument to backquote |
| 236 | indicates a value that isn't constant. Backquote evaluates the |
| 237 | argument of @samp{,} and puts the value in the list structure: |
| 238 | |
| 239 | @example |
| 240 | @group |
| 241 | (list 'a 'list 'of (+ 2 3) 'elements) |
| 242 | @result{} (a list of 5 elements) |
| 243 | @end group |
| 244 | @group |
| 245 | `(a list of ,(+ 2 3) elements) |
| 246 | @result{} (a list of 5 elements) |
| 247 | @end group |
| 248 | @end example |
| 249 | |
| 250 | Substitution with @samp{,} is allowed at deeper levels of the list |
| 251 | structure also. For example: |
| 252 | |
| 253 | @example |
| 254 | @group |
| 255 | (defmacro t-becomes-nil (variable) |
| 256 | `(if (eq ,variable t) |
| 257 | (setq ,variable nil))) |
| 258 | @end group |
| 259 | |
| 260 | @group |
| 261 | (t-becomes-nil foo) |
| 262 | @equiv{} (if (eq foo t) (setq foo nil)) |
| 263 | @end group |
| 264 | @end example |
| 265 | |
| 266 | @findex ,@@ @r{(with Backquote)} |
| 267 | @cindex splicing (with backquote) |
| 268 | You can also @dfn{splice} an evaluated value into the resulting list, |
| 269 | using the special marker @samp{,@@}. The elements of the spliced list |
| 270 | become elements at the same level as the other elements of the resulting |
| 271 | list. The equivalent code without using @samp{`} is often unreadable. |
| 272 | Here are some examples: |
| 273 | |
| 274 | @example |
| 275 | @group |
| 276 | (setq some-list '(2 3)) |
| 277 | @result{} (2 3) |
| 278 | @end group |
| 279 | @group |
| 280 | (cons 1 (append some-list '(4) some-list)) |
| 281 | @result{} (1 2 3 4 2 3) |
| 282 | @end group |
| 283 | @group |
| 284 | `(1 ,@@some-list 4 ,@@some-list) |
| 285 | @result{} (1 2 3 4 2 3) |
| 286 | @end group |
| 287 | |
| 288 | @group |
| 289 | (setq list '(hack foo bar)) |
| 290 | @result{} (hack foo bar) |
| 291 | @end group |
| 292 | @group |
| 293 | (cons 'use |
| 294 | (cons 'the |
| 295 | (cons 'words (append (cdr list) '(as elements))))) |
| 296 | @result{} (use the words foo bar as elements) |
| 297 | @end group |
| 298 | @group |
| 299 | `(use the words ,@@(cdr list) as elements) |
| 300 | @result{} (use the words foo bar as elements) |
| 301 | @end group |
| 302 | @end example |
| 303 | |
| 304 | In old Emacs versions, before version 19.29, @samp{`} used a different |
| 305 | syntax which required an extra level of parentheses around the entire |
| 306 | backquote construct. Likewise, each @samp{,} or @samp{,@@} substitution |
| 307 | required an extra level of parentheses surrounding both the @samp{,} or |
| 308 | @samp{,@@} and the following expression. The old syntax required |
| 309 | whitespace between the @samp{`}, @samp{,} or @samp{,@@} and the |
| 310 | following expression. |
| 311 | |
| 312 | This syntax is still accepted, for compatibility with old Emacs |
| 313 | versions, but we recommend not using it in new programs. |
| 314 | |
| 315 | @node Problems with Macros |
| 316 | @section Common Problems Using Macros |
| 317 | |
| 318 | The basic facts of macro expansion have counterintuitive consequences. |
| 319 | This section describes some important consequences that can lead to |
| 320 | trouble, and rules to follow to avoid trouble. |
| 321 | |
| 322 | @menu |
| 323 | * Wrong Time:: Do the work in the expansion, not in the macro. |
| 324 | * Argument Evaluation:: The expansion should evaluate each macro arg once. |
| 325 | * Surprising Local Vars:: Local variable bindings in the expansion |
| 326 | require special care. |
| 327 | * Eval During Expansion:: Don't evaluate them; put them in the expansion. |
| 328 | * Repeated Expansion:: Avoid depending on how many times expansion is done. |
| 329 | @end menu |
| 330 | |
| 331 | @node Wrong Time |
| 332 | @subsection Wrong Time |
| 333 | |
| 334 | The most common problem in writing macros is doing too some of the |
| 335 | real work prematurely---while expanding the macro, rather than in the |
| 336 | expansion itself. For instance, one real package had this nmacro |
| 337 | definition: |
| 338 | |
| 339 | @example |
| 340 | (defmacro my-set-buffer-multibyte (arg) |
| 341 | (if (fboundp 'set-buffer-multibyte) |
| 342 | (set-buffer-multibyte arg))) |
| 343 | @end example |
| 344 | |
| 345 | With this erroneous macro definition, the program worked fine when |
| 346 | interpreted but failed when compiled. This macro definition called |
| 347 | @code{set-buffer-multibyte} during compilation, which was wrong, and |
| 348 | then did nothing when the compiled package was run. The definition |
| 349 | that the programmer really wanted was this: |
| 350 | |
| 351 | @example |
| 352 | (defmacro my-set-buffer-multibyte (arg) |
| 353 | (if (fboundp 'set-buffer-multibyte) |
| 354 | `(set-buffer-multibyte ,arg))) |
| 355 | @end example |
| 356 | |
| 357 | @noindent |
| 358 | This macro expands, if appropriate, into a call to |
| 359 | @code{set-buffer-multibyte} that will be executed when the compiled |
| 360 | program is actually run. |
| 361 | |
| 362 | @node Argument Evaluation |
| 363 | @subsection Evaluating Macro Arguments Repeatedly |
| 364 | |
| 365 | When defining a macro you must pay attention to the number of times |
| 366 | the arguments will be evaluated when the expansion is executed. The |
| 367 | following macro (used to facilitate iteration) illustrates the problem. |
| 368 | This macro allows us to write a simple ``for'' loop such as one might |
| 369 | find in Pascal. |
| 370 | |
| 371 | @findex for |
| 372 | @smallexample |
| 373 | @group |
| 374 | (defmacro for (var from init to final do &rest body) |
| 375 | "Execute a simple \"for\" loop. |
| 376 | For example, (for i from 1 to 10 do (print i))." |
| 377 | (list 'let (list (list var init)) |
| 378 | (cons 'while (cons (list '<= var final) |
| 379 | (append body (list (list 'inc var))))))) |
| 380 | @end group |
| 381 | @result{} for |
| 382 | |
| 383 | @group |
| 384 | (for i from 1 to 3 do |
| 385 | (setq square (* i i)) |
| 386 | (princ (format "\n%d %d" i square))) |
| 387 | @expansion{} |
| 388 | @end group |
| 389 | @group |
| 390 | (let ((i 1)) |
| 391 | (while (<= i 3) |
| 392 | (setq square (* i i)) |
| 393 | (princ (format "%d %d" i square)) |
| 394 | (inc i))) |
| 395 | @end group |
| 396 | @group |
| 397 | |
| 398 | @print{}1 1 |
| 399 | @print{}2 4 |
| 400 | @print{}3 9 |
| 401 | @result{} nil |
| 402 | @end group |
| 403 | @end smallexample |
| 404 | |
| 405 | @noindent |
| 406 | The arguments @code{from}, @code{to}, and @code{do} in this macro are |
| 407 | ``syntactic sugar''; they are entirely ignored. The idea is that you |
| 408 | will write noise words (such as @code{from}, @code{to}, and @code{do}) |
| 409 | in those positions in the macro call. |
| 410 | |
| 411 | Here's an equivalent definition simplified through use of backquote: |
| 412 | |
| 413 | @smallexample |
| 414 | @group |
| 415 | (defmacro for (var from init to final do &rest body) |
| 416 | "Execute a simple \"for\" loop. |
| 417 | For example, (for i from 1 to 10 do (print i))." |
| 418 | `(let ((,var ,init)) |
| 419 | (while (<= ,var ,final) |
| 420 | ,@@body |
| 421 | (inc ,var)))) |
| 422 | @end group |
| 423 | @end smallexample |
| 424 | |
| 425 | Both forms of this definition (with backquote and without) suffer from |
| 426 | the defect that @var{final} is evaluated on every iteration. If |
| 427 | @var{final} is a constant, this is not a problem. If it is a more |
| 428 | complex form, say @code{(long-complex-calculation x)}, this can slow |
| 429 | down the execution significantly. If @var{final} has side effects, |
| 430 | executing it more than once is probably incorrect. |
| 431 | |
| 432 | @cindex macro argument evaluation |
| 433 | A well-designed macro definition takes steps to avoid this problem by |
| 434 | producing an expansion that evaluates the argument expressions exactly |
| 435 | once unless repeated evaluation is part of the intended purpose of the |
| 436 | macro. Here is a correct expansion for the @code{for} macro: |
| 437 | |
| 438 | @smallexample |
| 439 | @group |
| 440 | (let ((i 1) |
| 441 | (max 3)) |
| 442 | (while (<= i max) |
| 443 | (setq square (* i i)) |
| 444 | (princ (format "%d %d" i square)) |
| 445 | (inc i))) |
| 446 | @end group |
| 447 | @end smallexample |
| 448 | |
| 449 | Here is a macro definition that creates this expansion: |
| 450 | |
| 451 | @smallexample |
| 452 | @group |
| 453 | (defmacro for (var from init to final do &rest body) |
| 454 | "Execute a simple for loop: (for i from 1 to 10 do (print i))." |
| 455 | `(let ((,var ,init) |
| 456 | (max ,final)) |
| 457 | (while (<= ,var max) |
| 458 | ,@@body |
| 459 | (inc ,var)))) |
| 460 | @end group |
| 461 | @end smallexample |
| 462 | |
| 463 | Unfortunately, this fix introduces another problem, |
| 464 | described in the following section. |
| 465 | |
| 466 | @node Surprising Local Vars |
| 467 | @subsection Local Variables in Macro Expansions |
| 468 | |
| 469 | @ifnottex |
| 470 | In the previous section, the definition of @code{for} was fixed as |
| 471 | follows to make the expansion evaluate the macro arguments the proper |
| 472 | number of times: |
| 473 | |
| 474 | @smallexample |
| 475 | @group |
| 476 | (defmacro for (var from init to final do &rest body) |
| 477 | "Execute a simple for loop: (for i from 1 to 10 do (print i))." |
| 478 | @end group |
| 479 | @group |
| 480 | `(let ((,var ,init) |
| 481 | (max ,final)) |
| 482 | (while (<= ,var max) |
| 483 | ,@@body |
| 484 | (inc ,var)))) |
| 485 | @end group |
| 486 | @end smallexample |
| 487 | @end ifnottex |
| 488 | |
| 489 | The new definition of @code{for} has a new problem: it introduces a |
| 490 | local variable named @code{max} which the user does not expect. This |
| 491 | causes trouble in examples such as the following: |
| 492 | |
| 493 | @smallexample |
| 494 | @group |
| 495 | (let ((max 0)) |
| 496 | (for x from 0 to 10 do |
| 497 | (let ((this (frob x))) |
| 498 | (if (< max this) |
| 499 | (setq max this))))) |
| 500 | @end group |
| 501 | @end smallexample |
| 502 | |
| 503 | @noindent |
| 504 | The references to @code{max} inside the body of the @code{for}, which |
| 505 | are supposed to refer to the user's binding of @code{max}, really access |
| 506 | the binding made by @code{for}. |
| 507 | |
| 508 | The way to correct this is to use an uninterned symbol instead of |
| 509 | @code{max} (@pxref{Creating Symbols}). The uninterned symbol can be |
| 510 | bound and referred to just like any other symbol, but since it is |
| 511 | created by @code{for}, we know that it cannot already appear in the |
| 512 | user's program. Since it is not interned, there is no way the user can |
| 513 | put it into the program later. It will never appear anywhere except |
| 514 | where put by @code{for}. Here is a definition of @code{for} that works |
| 515 | this way: |
| 516 | |
| 517 | @smallexample |
| 518 | @group |
| 519 | (defmacro for (var from init to final do &rest body) |
| 520 | "Execute a simple for loop: (for i from 1 to 10 do (print i))." |
| 521 | (let ((tempvar (make-symbol "max"))) |
| 522 | `(let ((,var ,init) |
| 523 | (,tempvar ,final)) |
| 524 | (while (<= ,var ,tempvar) |
| 525 | ,@@body |
| 526 | (inc ,var))))) |
| 527 | @end group |
| 528 | @end smallexample |
| 529 | |
| 530 | @noindent |
| 531 | This creates an uninterned symbol named @code{max} and puts it in the |
| 532 | expansion instead of the usual interned symbol @code{max} that appears |
| 533 | in expressions ordinarily. |
| 534 | |
| 535 | @node Eval During Expansion |
| 536 | @subsection Evaluating Macro Arguments in Expansion |
| 537 | |
| 538 | Another problem can happen if the macro definition itself |
| 539 | evaluates any of the macro argument expressions, such as by calling |
| 540 | @code{eval} (@pxref{Eval}). If the argument is supposed to refer to the |
| 541 | user's variables, you may have trouble if the user happens to use a |
| 542 | variable with the same name as one of the macro arguments. Inside the |
| 543 | macro body, the macro argument binding is the most local binding of this |
| 544 | variable, so any references inside the form being evaluated do refer to |
| 545 | it. Here is an example: |
| 546 | |
| 547 | @example |
| 548 | @group |
| 549 | (defmacro foo (a) |
| 550 | (list 'setq (eval a) t)) |
| 551 | @result{} foo |
| 552 | @end group |
| 553 | @group |
| 554 | (setq x 'b) |
| 555 | (foo x) @expansion{} (setq b t) |
| 556 | @result{} t ; @r{and @code{b} has been set.} |
| 557 | ;; @r{but} |
| 558 | (setq a 'c) |
| 559 | (foo a) @expansion{} (setq a t) |
| 560 | @result{} t ; @r{but this set @code{a}, not @code{c}.} |
| 561 | |
| 562 | @end group |
| 563 | @end example |
| 564 | |
| 565 | It makes a difference whether the user's variable is named @code{a} or |
| 566 | @code{x}, because @code{a} conflicts with the macro argument variable |
| 567 | @code{a}. |
| 568 | |
| 569 | Another problem with calling @code{eval} in a macro definition is that |
| 570 | it probably won't do what you intend in a compiled program. The |
| 571 | byte-compiler runs macro definitions while compiling the program, when |
| 572 | the program's own computations (which you might have wished to access |
| 573 | with @code{eval}) don't occur and its local variable bindings don't |
| 574 | exist. |
| 575 | |
| 576 | To avoid these problems, @strong{don't evaluate an argument expression |
| 577 | while computing the macro expansion}. Instead, substitute the |
| 578 | expression into the macro expansion, so that its value will be computed |
| 579 | as part of executing the expansion. This is how the other examples in |
| 580 | this chapter work. |
| 581 | |
| 582 | @node Repeated Expansion |
| 583 | @subsection How Many Times is the Macro Expanded? |
| 584 | |
| 585 | Occasionally problems result from the fact that a macro call is |
| 586 | expanded each time it is evaluated in an interpreted function, but is |
| 587 | expanded only once (during compilation) for a compiled function. If the |
| 588 | macro definition has side effects, they will work differently depending |
| 589 | on how many times the macro is expanded. |
| 590 | |
| 591 | Therefore, you should avoid side effects in computation of the |
| 592 | macro expansion, unless you really know what you are doing. |
| 593 | |
| 594 | One special kind of side effect can't be avoided: constructing Lisp |
| 595 | objects. Almost all macro expansions include constructed lists; that is |
| 596 | the whole point of most macros. This is usually safe; there is just one |
| 597 | case where you must be careful: when the object you construct is part of a |
| 598 | quoted constant in the macro expansion. |
| 599 | |
| 600 | If the macro is expanded just once, in compilation, then the object is |
| 601 | constructed just once, during compilation. But in interpreted |
| 602 | execution, the macro is expanded each time the macro call runs, and this |
| 603 | means a new object is constructed each time. |
| 604 | |
| 605 | In most clean Lisp code, this difference won't matter. It can matter |
| 606 | only if you perform side-effects on the objects constructed by the macro |
| 607 | definition. Thus, to avoid trouble, @strong{avoid side effects on |
| 608 | objects constructed by macro definitions}. Here is an example of how |
| 609 | such side effects can get you into trouble: |
| 610 | |
| 611 | @lisp |
| 612 | @group |
| 613 | (defmacro empty-object () |
| 614 | (list 'quote (cons nil nil))) |
| 615 | @end group |
| 616 | |
| 617 | @group |
| 618 | (defun initialize (condition) |
| 619 | (let ((object (empty-object))) |
| 620 | (if condition |
| 621 | (setcar object condition)) |
| 622 | object)) |
| 623 | @end group |
| 624 | @end lisp |
| 625 | |
| 626 | @noindent |
| 627 | If @code{initialize} is interpreted, a new list @code{(nil)} is |
| 628 | constructed each time @code{initialize} is called. Thus, no side effect |
| 629 | survives between calls. If @code{initialize} is compiled, then the |
| 630 | macro @code{empty-object} is expanded during compilation, producing a |
| 631 | single ``constant'' @code{(nil)} that is reused and altered each time |
| 632 | @code{initialize} is called. |
| 633 | |
| 634 | One way to avoid pathological cases like this is to think of |
| 635 | @code{empty-object} as a funny kind of constant, not as a memory |
| 636 | allocation construct. You wouldn't use @code{setcar} on a constant such |
| 637 | as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)} |
| 638 | either. |