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