annotate doc/lispref/macros.texi @ 111610:d53ab813a8d6

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