*** empty log message ***
[emacs.git] / lispref / macros.texi
blob301dc124f39ff82da7b198763decd7aea84c79ad
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 Free Software Foundation, Inc. 
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/macros
6 @node Macros, Customization, Functions, Top
7 @chapter Macros
8 @cindex macros
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.
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.
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}.
25 @menu
26 * Simple Macro::            A basic example.
27 * Expansion::               How, when and why macros are expanded.
28 * Compiling Macros::        How macros are expanded by the compiler.
29 * Defining Macros::         How to write a macro definition.
30 * Backquote::               Easier construction of list structure.
31 * Problems with Macros::    Don't evaluate the macro arguments too many times.
32                               Don't hide the user's variables.
33 @end menu
35 @node Simple Macro
36 @section A Simple Example of a Macro
38   Suppose we would like to define a Lisp construct to increment a
39 variable value, much like the @code{++} operator in C.  We would like to
40 write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}.
41 Here's a macro definition that does the job:
43 @findex inc
44 @example
45 @group
46 (defmacro inc (var)
47    (list 'setq var (list '1+ var)))
48 @end group
49 @end example
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}.
58 @node Expansion
59 @section Expansion of a Macro Call
60 @cindex expansion of macros
61 @cindex macro call
63   A macro call looks just like a function call in that it is a list which
64 starts with the name of the macro.  The rest of the elements of the list
65 are the arguments of the macro.
67   Evaluation of the macro call begins like evaluation of a function call
68 except for one crucial difference: the macro arguments are the actual
69 expressions appearing in the macro call.  They are not evaluated before
70 they are given to the macro definition.  By contrast, the arguments of a
71 function are results of evaluating the elements of the function call
72 list.
74   Having obtained the arguments, Lisp invokes the macro definition just
75 as a function is invoked.  The argument variables of the macro are bound
76 to the argument values from the macro call, or to a list of them in the
77 case of a @code{&rest} argument.  And the macro body executes and
78 returns its value just as a function body does.
80   The second crucial difference between macros and functions is that the
81 value returned by the macro body is not the value of the macro call.
82 Instead, it is an alternate expression for computing that value, also
83 known as the @dfn{expansion} of the macro.  The Lisp interpreter
84 proceeds to evaluate the expansion as soon as it comes back from the
85 macro.
87   Since the expansion is evaluated in the normal manner, it may contain
88 calls to other macros.  It may even be a call to the same macro, though
89 this is unusual.
91   You can see the expansion of a given macro call by calling
92 @code{macroexpand}.
94 @defun macroexpand form &optional environment
95 @cindex macro expansion
96 This function expands @var{form}, if it is a macro call.  If the result
97 is another macro call, it is expanded in turn, until something which is
98 not a macro call results.  That is the value returned by
99 @code{macroexpand}.  If @var{form} is not a macro call to begin with, it
100 is returned as given.
102 Note that @code{macroexpand} does not look at the subexpressions of
103 @var{form} (although some macro definitions may do so).  Even if they
104 are macro calls themselves, @code{macroexpand} does not expand them.
106 The function @code{macroexpand} does not expand calls to inline functions.
107 Normally there is no need for that, since a call to an inline function is
108 no harder to understand than a call to an ordinary function.
110 If @var{environment} is provided, it specifies an alist of macro
111 definitions that shadow the currently defined macros.  Byte compilation
112 uses this feature.
114 @smallexample
115 @group
116 (defmacro inc (var)
117     (list 'setq var (list '1+ var)))
118      @result{} inc
119 @end group
121 @group
122 (macroexpand '(inc r))
123      @result{} (setq r (1+ r))
124 @end group
126 @group
127 (defmacro inc2 (var1 var2)
128     (list 'progn (list 'inc var1) (list 'inc var2)))
129      @result{} inc2
130 @end group
132 @group
133 (macroexpand '(inc2 r s))
134      @result{} (progn (inc r) (inc s))  ; @r{@code{inc} not expanded here.}
135 @end group
136 @end smallexample
137 @end defun
139 @node Compiling Macros
140 @section Macros and Byte Compilation
141 @cindex byte-compiling macros
143   You might ask why we take the trouble to compute an expansion for a
144 macro and then evaluate the expansion.  Why not have the macro body
145 produce the desired results directly?  The reason has to do with
146 compilation.
148   When a macro call appears in a Lisp program being compiled, the Lisp
149 compiler calls the macro definition just as the interpreter would, and
150 receives an expansion.  But instead of evaluating this expansion, it
151 compiles the expansion as if it had appeared directly in the program.
152 As a result, the compiled code produces the value and side effects
153 intended for the macro, but executes at full compiled speed.  This would
154 not work if the macro body computed the value and side effects
155 itself---they would be computed at compile time, which is not useful.
157   In order for compilation of macro calls to work, the macros must
158 already be defined in Lisp when the calls to them are compiled.  The
159 compiler has a special feature to help you do this: if a file being
160 compiled contains a @code{defmacro} form, the macro is defined
161 temporarily for the rest of the compilation of that file.  To make this
162 feature work, you must put the @code{defmacro} in the same file where it
163 is used, and before its first use.
165   Byte-compiling a file executes any @code{require} calls at top-level
166 in the file.  This is in case the file needs the required packages for
167 proper compilation.  One way to ensure that necessary macro definitions
168 are available during compilation is to require the files that define
169 them (@pxref{Named Features}).  To avoid loading the macro definition files
170 when someone @emph{runs} the compiled program, write
171 @code{eval-when-compile} around the @code{require} calls (@pxref{Eval
172 During Compile}).
174 @node Defining Macros
175 @section Defining Macros
177   A Lisp macro is a list whose @sc{car} is @code{macro}.  Its @sc{cdr} should
178 be a function; expansion of the macro works by applying the function
179 (with @code{apply}) to the list of unevaluated argument-expressions
180 from the macro call.
182   It is possible to use an anonymous Lisp macro just like an anonymous
183 function, but this is never done, because it does not make sense to pass
184 an anonymous macro to functionals such as @code{mapcar}.  In practice,
185 all Lisp macros have names, and they are usually defined with the
186 special form @code{defmacro}.
188 @defspec defmacro name argument-list body-forms@dots{}
189 @code{defmacro} defines the symbol @var{name} as a macro that looks
190 like this:
192 @example
193 (macro lambda @var{argument-list} . @var{body-forms})
194 @end example
196 (Note that the @sc{cdr} of this list is a function---a lambda expression.)
197 This macro object is stored in the function cell of @var{name}.  The
198 value returned by evaluating the @code{defmacro} form is @var{name}, but
199 usually we ignore this value.
201 The shape and meaning of @var{argument-list} is the same as in a
202 function, and the keywords @code{&rest} and @code{&optional} may be used
203 (@pxref{Argument List}).  Macros may have a documentation string, but
204 any @code{interactive} declaration is ignored since macros cannot be
205 called interactively.
206 @end defspec
208 @node Backquote
209 @section Backquote
210 @cindex backquote (list substitution)
211 @cindex ` (list substitution)
212 @findex `
214   Macros often need to construct large list structures from a mixture of
215 constants and nonconstant parts.  To make this easier, use the @samp{`}
216 syntax (usually called @dfn{backquote}).
218   Backquote allows you to quote a list, but selectively evaluate
219 elements of that list.  In the simplest case, it is identical to the
220 special form @code{quote} (@pxref{Quoting}).  For example, these
221 two forms yield identical results:
223 @example
224 @group
225 `(a list of (+ 2 3) elements)
226      @result{} (a list of (+ 2 3) elements)
227 @end group
228 @group
229 '(a list of (+ 2 3) elements)
230      @result{} (a list of (+ 2 3) elements)
231 @end group
232 @end example
234 @findex , @r{(with Backquote)}
235 The special marker @samp{,} inside of the argument to backquote
236 indicates a value that isn't constant.  Backquote evaluates the
237 argument of @samp{,} and puts the value in the list structure:
239 @example
240 @group
241 (list 'a 'list 'of (+ 2 3) 'elements)
242      @result{} (a list of 5 elements)
243 @end group
244 @group
245 `(a list of ,(+ 2 3) elements)
246      @result{} (a list of 5 elements)
247 @end group
248 @end example
250   Substitution with @samp{,} is allowed at deeper levels of the list
251 structure also.  For example:
253 @example
254 @group
255 (defmacro t-becomes-nil (variable)
256   `(if (eq ,variable t)
257        (setq ,variable nil)))
258 @end group
260 @group
261 (t-becomes-nil foo)
262      @equiv{} (if (eq foo t) (setq foo nil))
263 @end group
264 @end example
266 @findex ,@@ @r{(with Backquote)}
267 @cindex splicing (with backquote)
268   You can also @dfn{splice} an evaluated value into the resulting list,
269 using the special marker @samp{,@@}.  The elements of the spliced list
270 become elements at the same level as the other elements of the resulting
271 list.  The equivalent code without using @samp{`} is often unreadable.
272 Here are some examples:
274 @example
275 @group
276 (setq some-list '(2 3))
277      @result{} (2 3)
278 @end group
279 @group
280 (cons 1 (append some-list '(4) some-list))
281      @result{} (1 2 3 4 2 3)
282 @end group
283 @group
284 `(1 ,@@some-list 4 ,@@some-list)
285      @result{} (1 2 3 4 2 3)
286 @end group
288 @group
289 (setq list '(hack foo bar))
290      @result{} (hack foo bar)
291 @end group
292 @group
293 (cons 'use
294   (cons 'the
295     (cons 'words (append (cdr list) '(as elements)))))
296      @result{} (use the words foo bar as elements)
297 @end group
298 @group
299 `(use the words ,@@(cdr list) as elements)
300      @result{} (use the words foo bar as elements)
301 @end group
302 @end example
304 In old Emacs versions, before version 19.29, @samp{`} used a different
305 syntax which required an extra level of parentheses around the entire
306 backquote construct.  Likewise, each @samp{,} or @samp{,@@} substitution
307 required an extra level of parentheses surrounding both the @samp{,} or
308 @samp{,@@} and the following expression.  The old syntax required
309 whitespace between the @samp{`}, @samp{,} or @samp{,@@} and the
310 following expression.
312 This syntax is still accepted, for compatibility with old Emacs
313 versions, but we recommend not using it in new programs.
315 @node Problems with Macros
316 @section Common Problems Using Macros
318   The basic facts of macro expansion have counterintuitive consequences.
319 This section describes some important consequences that can lead to
320 trouble, and rules to follow to avoid trouble.
322 @menu
323 * Argument Evaluation::    The expansion should evaluate each macro arg once.
324 * Surprising Local Vars::  Local variable bindings in the expansion
325                               require special care.
326 * Eval During Expansion::  Don't evaluate them; put them in the expansion.
327 * Repeated Expansion::     Avoid depending on how many times expansion is done.
328 @end menu
330 @node Argument Evaluation
331 @subsection Evaluating Macro Arguments Repeatedly
333   When defining a macro you must pay attention to the number of times
334 the arguments will be evaluated when the expansion is executed.  The
335 following macro (used to facilitate iteration) illustrates the problem.
336 This macro allows us to write a simple ``for'' loop such as one might
337 find in Pascal.
339 @findex for
340 @smallexample
341 @group
342 (defmacro for (var from init to final do &rest body)
343   "Execute a simple \"for\" loop.
344 For example, (for i from 1 to 10 do (print i))."
345   (list 'let (list (list var init))
346         (cons 'while (cons (list '<= var final)
347                            (append body (list (list 'inc var)))))))
348 @end group
349 @result{} for
351 @group
352 (for i from 1 to 3 do
353    (setq square (* i i))
354    (princ (format "\n%d %d" i square)))
355 @expansion{}
356 @end group
357 @group
358 (let ((i 1))
359   (while (<= i 3)
360     (setq square (* i i))
361     (princ (format "%d      %d" i square))
362     (inc i)))
363 @end group
364 @group
366      @print{}1       1
367      @print{}2       4
368      @print{}3       9
369 @result{} nil
370 @end group
371 @end smallexample
373 @noindent
374 The arguments @code{from}, @code{to}, and @code{do} in this macro are
375 ``syntactic sugar''; they are entirely ignored.  The idea is that you
376 will write noise words (such as @code{from}, @code{to}, and @code{do})
377 in those positions in the macro call.
379 Here's an equivalent definition simplified through use of backquote:
381 @smallexample
382 @group
383 (defmacro for (var from init to final do &rest body)
384   "Execute a simple \"for\" loop.
385 For example, (for i from 1 to 10 do (print i))."
386   `(let ((,var ,init))
387      (while (<= ,var ,final)
388        ,@@body
389        (inc ,var))))
390 @end group
391 @end smallexample
393 Both forms of this definition (with backquote and without) suffer from
394 the defect that @var{final} is evaluated on every iteration.  If
395 @var{final} is a constant, this is not a problem.  If it is a more
396 complex form, say @code{(long-complex-calculation x)}, this can slow
397 down the execution significantly.  If @var{final} has side effects,
398 executing it more than once is probably incorrect.
400 @cindex macro argument evaluation
401 A well-designed macro definition takes steps to avoid this problem by
402 producing an expansion that evaluates the argument expressions exactly
403 once unless repeated evaluation is part of the intended purpose of the
404 macro.  Here is a correct expansion for the @code{for} macro:
406 @smallexample
407 @group
408 (let ((i 1)
409       (max 3))
410   (while (<= i max)
411     (setq square (* i i))
412     (princ (format "%d      %d" i square))
413     (inc i)))
414 @end group
415 @end smallexample
417 Here is a macro definition that creates this expansion: 
419 @smallexample
420 @group
421 (defmacro for (var from init to final do &rest body)
422   "Execute a simple for loop: (for i from 1 to 10 do (print i))."
423   `(let ((,var ,init)
424          (max ,final))
425      (while (<= ,var max)
426        ,@@body
427        (inc ,var))))
428 @end group
429 @end smallexample
431   Unfortunately, this fix introduces another problem,
432 described in the following section.
434 @node Surprising Local Vars
435 @subsection Local Variables in Macro Expansions
437 @ifnottex
438   In the previous section, the definition of @code{for} was fixed as
439 follows to make the expansion evaluate the macro arguments the proper
440 number of times:
442 @smallexample
443 @group
444 (defmacro for (var from init to final do &rest body)
445   "Execute a simple for loop: (for i from 1 to 10 do (print i))."
446 @end group
447 @group
448   `(let ((,var ,init)
449          (max ,final))
450      (while (<= ,var max)
451        ,@@body
452        (inc ,var))))
453 @end group
454 @end smallexample
455 @end ifnottex
457   The new definition of @code{for} has a new problem: it introduces a
458 local variable named @code{max} which the user does not expect.  This
459 causes trouble in examples such as the following:
461 @smallexample
462 @group
463 (let ((max 0))
464   (for x from 0 to 10 do
465     (let ((this (frob x)))
466       (if (< max this)
467           (setq max this)))))
468 @end group
469 @end smallexample
471 @noindent
472 The references to @code{max} inside the body of the @code{for}, which
473 are supposed to refer to the user's binding of @code{max}, really access
474 the binding made by @code{for}.
476 The way to correct this is to use an uninterned symbol instead of
477 @code{max} (@pxref{Creating Symbols}).  The uninterned symbol can be
478 bound and referred to just like any other symbol, but since it is
479 created by @code{for}, we know that it cannot already appear in the
480 user's program.  Since it is not interned, there is no way the user can
481 put it into the program later.  It will never appear anywhere except
482 where put by @code{for}.  Here is a definition of @code{for} that works
483 this way:
485 @smallexample
486 @group
487 (defmacro for (var from init to final do &rest body)
488   "Execute a simple for loop: (for i from 1 to 10 do (print i))."
489   (let ((tempvar (make-symbol "max")))
490     `(let ((,var ,init)
491            (,tempvar ,final))
492        (while (<= ,var ,tempvar)
493          ,@@body
494          (inc ,var)))))
495 @end group
496 @end smallexample
498 @noindent
499 This creates an uninterned symbol named @code{max} and puts it in the
500 expansion instead of the usual interned symbol @code{max} that appears
501 in expressions ordinarily.
503 @node Eval During Expansion
504 @subsection Evaluating Macro Arguments in Expansion
506   Another problem can happen if the macro definition itself
507 evaluates any of the macro argument expressions, such as by calling
508 @code{eval} (@pxref{Eval}).  If the argument is supposed to refer to the
509 user's variables, you may have trouble if the user happens to use a
510 variable with the same name as one of the macro arguments.  Inside the
511 macro body, the macro argument binding is the most local binding of this
512 variable, so any references inside the form being evaluated do refer to
513 it.  Here is an example:
515 @example
516 @group
517 (defmacro foo (a)
518   (list 'setq (eval a) t))
519      @result{} foo
520 @end group
521 @group
522 (setq x 'b)
523 (foo x) @expansion{} (setq b t)
524      @result{} t                  ; @r{and @code{b} has been set.}
525 ;; @r{but}
526 (setq a 'c)
527 (foo a) @expansion{} (setq a t)
528      @result{} t                  ; @r{but this set @code{a}, not @code{c}.}
530 @end group
531 @end example
533   It makes a difference whether the user's variable is named @code{a} or
534 @code{x}, because @code{a} conflicts with the macro argument variable
535 @code{a}.
537   Another problem with calling @code{eval} in a macro definition is that
538 it probably won't do what you intend in a compiled program.  The
539 byte-compiler runs macro definitions while compiling the program, when
540 the program's own computations (which you might have wished to access
541 with @code{eval}) don't occur and its local variable bindings don't
542 exist.
544   To avoid these problems, @strong{don't evaluate an argument expression
545 while computing the macro expansion}.  Instead, substitute the
546 expression into the macro expansion, so that its value will be computed
547 as part of executing the expansion.  This is how the other examples in
548 this chapter work.
550 @node Repeated Expansion
551 @subsection How Many Times is the Macro Expanded?
553   Occasionally problems result from the fact that a macro call is
554 expanded each time it is evaluated in an interpreted function, but is
555 expanded only once (during compilation) for a compiled function.  If the
556 macro definition has side effects, they will work differently depending
557 on how many times the macro is expanded.
559   Therefore, you should avoid side effects in computation of the
560 macro expansion, unless you really know what you are doing.
562   One special kind of side effect can't be avoided: constructing Lisp
563 objects.  Almost all macro expansions include constructed lists; that is
564 the whole point of most macros.  This is usually safe; there is just one
565 case where you must be careful: when the object you construct is part of a
566 quoted constant in the macro expansion.
568   If the macro is expanded just once, in compilation, then the object is
569 constructed just once, during compilation.  But in interpreted
570 execution, the macro is expanded each time the macro call runs, and this
571 means a new object is constructed each time.
573   In most clean Lisp code, this difference won't matter.  It can matter
574 only if you perform side-effects on the objects constructed by the macro
575 definition.  Thus, to avoid trouble, @strong{avoid side effects on
576 objects constructed by macro definitions}.  Here is an example of how
577 such side effects can get you into trouble:
579 @lisp
580 @group
581 (defmacro empty-object ()
582   (list 'quote (cons nil nil)))
583 @end group
585 @group
586 (defun initialize (condition)
587   (let ((object (empty-object)))
588     (if condition
589         (setcar object condition))
590     object))
591 @end group
592 @end lisp
594 @noindent
595 If @code{initialize} is interpreted, a new list @code{(nil)} is
596 constructed each time @code{initialize} is called.  Thus, no side effect
597 survives between calls.  If @code{initialize} is compiled, then the
598 macro @code{empty-object} is expanded during compilation, producing a
599 single ``constant'' @code{(nil)} that is reused and altered each time
600 @code{initialize} is called.
602 One way to avoid pathological cases like this is to think of
603 @code{empty-object} as a funny kind of constant, not as a memory
604 allocation construct.  You wouldn't use @code{setcar} on a constant such
605 as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)}
606 either.