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