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