Mercurial > emacs
annotate lispref/macros.texi @ 12080:862907031e94
(Fx_create_frame): Make sure icon_name is a string or nil.
author | Karl Heuer <kwzh@gnu.org> |
---|---|
date | Mon, 05 Jun 1995 17:41:10 +0000 |
parents | 73dc8205d259 |
children | a6eb5f12b0f3 |
rev | line source |
---|---|
6558 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. | |
4 @c See the file elisp.texi for copying conditions. | |
5 @setfilename ../info/macros | |
6 @node Macros, Loading, 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 @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 file that defines | |
167 them. @xref{Features}. | |
168 | |
169 @node Defining Macros | |
170 @section Defining Macros | |
171 | |
172 A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should | |
173 be a function; expansion of the macro works by applying the function | |
174 (with @code{apply}) to the list of unevaluated argument-expressions | |
175 from the macro call. | |
176 | |
177 It is possible to use an anonymous Lisp macro just like an anonymous | |
178 function, but this is never done, because it does not make sense to pass | |
179 an anonymous macro to mapping functions such as @code{mapcar}. In | |
180 practice, all Lisp macros have names, and they are usually defined with | |
181 the special form @code{defmacro}. | |
182 | |
183 @defspec defmacro name argument-list body-forms@dots{} | |
184 @code{defmacro} defines the symbol @var{name} as a macro that looks | |
185 like this: | |
186 | |
187 @example | |
188 (macro lambda @var{argument-list} . @var{body-forms}) | |
189 @end example | |
190 | |
191 This macro object is stored in the function cell of @var{name}. The | |
192 value returned by evaluating the @code{defmacro} form is @var{name}, but | |
193 usually we ignore this value. | |
194 | |
195 The shape and meaning of @var{argument-list} is the same as in a | |
196 function, and the keywords @code{&rest} and @code{&optional} may be used | |
197 (@pxref{Argument List}). Macros may have a documentation string, but | |
198 any @code{interactive} declaration is ignored since macros cannot be | |
199 called interactively. | |
200 @end defspec | |
201 | |
202 @node Backquote | |
203 @section Backquote | |
204 @cindex backquote (list substitution) | |
205 @cindex ` (list substitution) | |
12067 | 206 @findex ` |
6558 | 207 |
208 Macros often need to construct large list structures from a mixture of | |
209 constants and nonconstant parts. To make this easier, use the macro | |
210 @code{`} (often called @dfn{backquote}). | |
211 | |
212 Backquote allows you to quote a list, but selectively evaluate | |
213 elements of that list. In the simplest case, it is identical to the | |
214 special form @code{quote} (@pxref{Quoting}). For example, these | |
215 two forms yield identical results: | |
216 | |
217 @example | |
218 @group | |
12067 | 219 `(a list of (+ 2 3) elements) |
6558 | 220 @result{} (a list of (+ 2 3) elements) |
221 @end group | |
222 @group | |
12067 | 223 '(a list of (+ 2 3) elements) |
6558 | 224 @result{} (a list of (+ 2 3) elements) |
225 @end group | |
226 @end example | |
227 | |
7194
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
228 @findex , @r{(with Backquote)} |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
229 The special marker @code{,} inside of the argument to backquote |
6558 | 230 indicates a value that isn't constant. Backquote evaluates the |
231 argument of @code{,} and puts the value in the list structure: | |
232 | |
233 @example | |
234 @group | |
235 (list 'a 'list 'of (+ 2 3) 'elements) | |
236 @result{} (a list of 5 elements) | |
237 @end group | |
238 @group | |
12067 | 239 `(a list of ,(+ 2 3) elements) |
6558 | 240 @result{} (a list of 5 elements) |
241 @end group | |
242 @end example | |
243 | |
7194
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
244 @findex ,@@ @r{(with Backquote)} |
6558 | 245 @cindex splicing (with backquote) |
246 You can also @dfn{splice} an evaluated value into the resulting list, | |
247 using the special marker @code{,@@}. The elements of the spliced list | |
248 become elements at the same level as the other elements of the resulting | |
249 list. The equivalent code without using @code{`} is often unreadable. | |
250 Here are some examples: | |
251 | |
252 @example | |
253 @group | |
254 (setq some-list '(2 3)) | |
255 @result{} (2 3) | |
256 @end group | |
257 @group | |
258 (cons 1 (append some-list '(4) some-list)) | |
259 @result{} (1 2 3 4 2 3) | |
260 @end group | |
261 @group | |
12067 | 262 `(1 ,@@some-list 4 ,@@some-list) |
6558 | 263 @result{} (1 2 3 4 2 3) |
264 @end group | |
265 | |
266 @group | |
267 (setq list '(hack foo bar)) | |
268 @result{} (hack foo bar) | |
269 @end group | |
270 @group | |
271 (cons 'use | |
272 (cons 'the | |
273 (cons 'words (append (cdr list) '(as elements))))) | |
274 @result{} (use the words foo bar as elements) | |
275 @end group | |
276 @group | |
12067 | 277 `(use the words ,@@(cdr list) as elements) |
6558 | 278 @result{} (use the words foo bar as elements) |
279 @end group | |
280 @end example | |
281 | |
12067 | 282 @quotation |
283 Before Emacs version 19.29, @code{`} used a different syntax which | |
284 required an extra level of parentheses around the entire backquote | |
285 construct. Likewise, each @code{,} or @code{,@@} substition required an | |
286 extra level of parentheses surrounding both the @code{,} or @code{,@@} | |
287 and the following expression. The old syntax required whitespace | |
288 between the @code{`}, @code{,} or @code{,@@} and the following | |
289 expression. | |
6558 | 290 |
12067 | 291 This syntax is still accepted, but no longer recommended except for |
292 compatibility with old Emacs versions. | |
6558 | 293 @end quotation |
294 | |
295 @node Problems with Macros | |
296 @section Common Problems Using Macros | |
297 | |
298 The basic facts of macro expansion have counterintuitive consequences. | |
299 This section describes some important consequences that can lead to | |
300 trouble, and rules to follow to avoid trouble. | |
301 | |
302 @menu | |
303 * Argument Evaluation:: The expansion should evaluate each macro arg once. | |
304 * Surprising Local Vars:: Local variable bindings in the expansion | |
305 require special care. | |
306 * Eval During Expansion:: Don't evaluate them; put them in the expansion. | |
307 * Repeated Expansion:: Avoid depending on how many times expansion is done. | |
308 @end menu | |
309 | |
310 @node Argument Evaluation | |
311 @subsection Evaluating Macro Arguments Repeatedly | |
312 | |
313 When defining a macro you must pay attention to the number of times | |
314 the arguments will be evaluated when the expansion is executed. The | |
315 following macro (used to facilitate iteration) illustrates the problem. | |
316 This macro allows us to write a simple ``for'' loop such as one might | |
317 find in Pascal. | |
318 | |
319 @findex for | |
320 @smallexample | |
321 @group | |
322 (defmacro for (var from init to final do &rest body) | |
323 "Execute a simple \"for\" loop. | |
324 For example, (for i from 1 to 10 do (print i))." | |
325 (list 'let (list (list var init)) | |
326 (cons 'while (cons (list '<= var final) | |
327 (append body (list (list 'inc var))))))) | |
328 @end group | |
329 @result{} for | |
330 | |
331 @group | |
332 (for i from 1 to 3 do | |
333 (setq square (* i i)) | |
334 (princ (format "\n%d %d" i square))) | |
335 @expansion{} | |
336 @end group | |
337 @group | |
338 (let ((i 1)) | |
339 (while (<= i 3) | |
340 (setq square (* i i)) | |
341 (princ (format "%d %d" i square)) | |
342 (inc i))) | |
343 @end group | |
344 @group | |
345 | |
346 @print{}1 1 | |
347 @print{}2 4 | |
348 @print{}3 9 | |
349 @result{} nil | |
350 @end group | |
351 @end smallexample | |
352 | |
353 @noindent | |
354 (The arguments @code{from}, @code{to}, and @code{do} in this macro are | |
355 ``syntactic sugar''; they are entirely ignored. The idea is that you | |
356 will write noise words (such as @code{from}, @code{to}, and @code{do}) | |
357 in those positions in the macro call.) | |
358 | |
7194
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
359 Here's an equivalent definition simplified through use of backquote: |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
360 |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
361 @smallexample |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
362 @group |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
363 (defmacro for (var from init to final do &rest body) |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
364 "Execute a simple \"for\" loop. |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
365 For example, (for i from 1 to 10 do (print i))." |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
366 (` (let (((, var) (, init))) |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
367 (while (<= (, var) (, final)) |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
368 (,@@ body) |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
369 (inc (, var)))))) |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
370 @end group |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
371 @end smallexample |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
372 |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
373 Both forms of this definition (with backquote and without) suffer from |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
374 the defect that @var{final} is evaluated on every iteration. If |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
375 @var{final} is a constant, this is not a problem. If it is a more |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
376 complex form, say @code{(long-complex-calculation x)}, this can slow |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
377 down the execution significantly. If @var{final} has side effects, |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
378 executing it more than once is probably incorrect. |
6558 | 379 |
380 @cindex macro argument evaluation | |
381 A well-designed macro definition takes steps to avoid this problem by | |
382 producing an expansion that evaluates the argument expressions exactly | |
383 once unless repeated evaluation is part of the intended purpose of the | |
384 macro. Here is a correct expansion for the @code{for} macro: | |
385 | |
386 @smallexample | |
387 @group | |
388 (let ((i 1) | |
389 (max 3)) | |
390 (while (<= i max) | |
391 (setq square (* i i)) | |
392 (princ (format "%d %d" i square)) | |
393 (inc i))) | |
394 @end group | |
395 @end smallexample | |
396 | |
397 Here is a macro definition that creates this expansion: | |
398 | |
399 @smallexample | |
400 @group | |
401 (defmacro for (var from init to final do &rest body) | |
402 "Execute a simple for loop: (for i from 1 to 10 do (print i))." | |
403 (` (let (((, var) (, init)) | |
404 (max (, final))) | |
405 (while (<= (, var) max) | |
406 (,@@ body) | |
407 (inc (, var)))))) | |
408 @end group | |
409 @end smallexample | |
410 | |
411 Unfortunately, this introduces another problem. | |
412 @ifinfo | |
413 Proceed to the following node. | |
414 @end ifinfo | |
415 | |
416 @node Surprising Local Vars | |
417 @subsection Local Variables in Macro Expansions | |
418 | |
419 @ifinfo | |
420 In the previous section, the definition of @code{for} was fixed as | |
421 follows to make the expansion evaluate the macro arguments the proper | |
422 number of times: | |
423 | |
424 @smallexample | |
425 @group | |
426 (defmacro for (var from init to final do &rest body) | |
427 "Execute a simple for loop: (for i from 1 to 10 do (print i))." | |
428 @end group | |
429 @group | |
430 (` (let (((, var) (, init)) | |
431 (max (, final))) | |
432 (while (<= (, var) max) | |
433 (,@@ body) | |
434 (inc (, var)))))) | |
435 @end group | |
436 @end smallexample | |
437 @end ifinfo | |
438 | |
439 The new definition of @code{for} has a new problem: it introduces a | |
440 local variable named @code{max} which the user does not expect. This | |
441 causes trouble in examples such as the following: | |
442 | |
7734 | 443 @smallexample |
6558 | 444 @group |
445 (let ((max 0)) | |
446 (for x from 0 to 10 do | |
447 (let ((this (frob x))) | |
448 (if (< max this) | |
449 (setq max this))))) | |
450 @end group | |
7734 | 451 @end smallexample |
6558 | 452 |
453 @noindent | |
454 The references to @code{max} inside the body of the @code{for}, which | |
455 are supposed to refer to the user's binding of @code{max}, really access | |
456 the binding made by @code{for}. | |
457 | |
458 The way to correct this is to use an uninterned symbol instead of | |
459 @code{max} (@pxref{Creating Symbols}). The uninterned symbol can be | |
7194
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
460 bound and referred to just like any other symbol, but since it is |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
461 created by @code{for}, we know that it cannot already appear in the |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
462 user's program. Since it is not interned, there is no way the user can |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
463 put it into the program later. It will never appear anywhere except |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
464 where put by @code{for}. Here is a definition of @code{for} that works |
3112fb627aa0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
465 this way: |
6558 | 466 |
467 @smallexample | |
468 @group | |
469 (defmacro for (var from init to final do &rest body) | |
470 "Execute a simple for loop: (for i from 1 to 10 do (print i))." | |
471 (let ((tempvar (make-symbol "max"))) | |
472 (` (let (((, var) (, init)) | |
473 ((, tempvar) (, final))) | |
474 (while (<= (, var) (, tempvar)) | |
475 (,@@ body) | |
476 (inc (, var))))))) | |
477 @end group | |
478 @end smallexample | |
479 | |
480 @noindent | |
481 This creates an uninterned symbol named @code{max} and puts it in the | |
482 expansion instead of the usual interned symbol @code{max} that appears | |
483 in expressions ordinarily. | |
484 | |
485 @node Eval During Expansion | |
486 @subsection Evaluating Macro Arguments in Expansion | |
487 | |
488 Another problem can happen if you evaluate any of the macro argument | |
489 expressions during the computation of the expansion, such as by calling | |
490 @code{eval} (@pxref{Eval}). If the argument is supposed to refer to the | |
491 user's variables, you may have trouble if the user happens to use a | |
492 variable with the same name as one of the macro arguments. Inside the | |
493 macro body, the macro argument binding is the most local binding of this | |
494 variable, so any references inside the form being evaluated do refer | |
495 to it. Here is an example: | |
496 | |
497 @example | |
498 @group | |
499 (defmacro foo (a) | |
500 (list 'setq (eval a) t)) | |
501 @result{} foo | |
502 @end group | |
503 @group | |
504 (setq x 'b) | |
505 (foo x) @expansion{} (setq b t) | |
506 @result{} t ; @r{and @code{b} has been set.} | |
507 ;; @r{but} | |
508 (setq a 'c) | |
509 (foo a) @expansion{} (setq a t) | |
510 @result{} t ; @r{but this set @code{a}, not @code{c}.} | |
511 | |
512 @end group | |
513 @end example | |
514 | |
515 It makes a difference whether the user's variable is named @code{a} or | |
516 @code{x}, because @code{a} conflicts with the macro argument variable | |
517 @code{a}. | |
518 | |
519 Another reason not to call @code{eval} in a macro definition is that | |
520 it probably won't do what you intend in a compiled program. The | |
521 byte-compiler runs macro definitions while compiling the program, when | |
522 the program's own computations (which you might have wished to access | |
523 with @code{eval}) don't occur and its local variable bindings don't | |
524 exist. | |
525 | |
526 The safe way to work with the run-time value of an expression is to | |
527 put the expression into the macro expansion, so that its value is | |
528 computed as part of executing the expansion. | |
529 | |
530 @node Repeated Expansion | |
531 @subsection How Many Times is the Macro Expanded? | |
532 | |
533 Occasionally problems result from the fact that a macro call is | |
534 expanded each time it is evaluated in an interpreted function, but is | |
535 expanded only once (during compilation) for a compiled function. If the | |
536 macro definition has side effects, they will work differently depending | |
537 on how many times the macro is expanded. | |
538 | |
539 In particular, constructing objects is a kind of side effect. If the | |
540 macro is called once, then the objects are constructed only once. In | |
541 other words, the same structure of objects is used each time the macro | |
542 call is executed. In interpreted operation, the macro is reexpanded | |
543 each time, producing a fresh collection of objects each time. Usually | |
544 this does not matter---the objects have the same contents whether they | |
545 are shared or not. But if the surrounding program does side effects | |
546 on the objects, it makes a difference whether they are shared. Here is | |
547 an example: | |
548 | |
549 @lisp | |
550 @group | |
551 (defmacro empty-object () | |
552 (list 'quote (cons nil nil))) | |
553 @end group | |
554 | |
555 @group | |
556 (defun initialize (condition) | |
557 (let ((object (empty-object))) | |
558 (if condition | |
559 (setcar object condition)) | |
560 object)) | |
561 @end group | |
562 @end lisp | |
563 | |
564 @noindent | |
565 If @code{initialize} is interpreted, a new list @code{(nil)} is | |
566 constructed each time @code{initialize} is called. Thus, no side effect | |
567 survives between calls. If @code{initialize} is compiled, then the | |
568 macro @code{empty-object} is expanded during compilation, producing a | |
569 single ``constant'' @code{(nil)} that is reused and altered each time | |
570 @code{initialize} is called. | |
571 | |
572 One way to avoid pathological cases like this is to think of | |
573 @code{empty-object} as a funny kind of constant, not as a memory | |
574 allocation construct. You wouldn't use @code{setcar} on a constant such | |
575 as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)} | |
576 either. |