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