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