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