1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
|
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@page
@node Macros
@section Macros
At its best, programming in Lisp is an iterative process of building up a
language appropriate to the problem at hand, and then solving the problem in
that language. Defining new procedures is part of that, but Lisp also allows
the user to extend its syntax, with its famous @dfn{macros}.
@cindex macros
@cindex transformation
Macros are syntactic extensions which cause the expression that they appear in
to be transformed in some way @emph{before} being evaluated. In expressions that
are intended for macro transformation, the identifier that names the relevant
macro must appear as the first element, like this:
@lisp
(@var{macro-name} @var{macro-args} @dots{})
@end lisp
@cindex macro expansion
Macro expansion is a separate phase of evaluation, run before code is
interpreted or compiled. A macro is a program that runs on programs, translating
an embedded language into core Scheme.
@menu
* Defining Macros:: Binding macros, globally and locally.
* Syntax Rules:: Pattern-driven macros.
* Syntax Case:: Procedural, hygienic macros.
* Defmacros:: Lisp-style macros.
* Identifier Macros:: Identifier macros.
* Eval When:: Affecting the expand-time environment.
* Internal Macros:: Macros as first-class values.
@end menu
@node Defining Macros
@subsection Defining Macros
A macro is a binding between a keyword and a syntax transformer. Since it's
difficult to discuss @code{define-syntax} without discussing the format of
transformers, consider the following example macro definition:
@example
(define-syntax when
(syntax-rules ()
((when condition exp ...)
(if condition
(begin exp ...)))))
(when #t
(display "hey ho\n")
(display "let's go\n"))
@print{} hey ho
@print{} let's go
@end example
In this example, the @code{when} binding is bound with @code{define-syntax}.
Syntax transformers are discussed in more depth in @ref{Syntax Rules} and
@ref{Syntax Case}.
@deffn {Syntax} define-syntax keyword transformer
Bind @var{keyword} to the syntax transformer obtained by evaluating
@var{transformer}.
After a macro has been defined, further instances of @var{keyword} in Scheme
source code will invoke the syntax transformer defined by @var{transformer}.
@end deffn
One can also establish local syntactic bindings with @code{let-syntax}.
@deffn {Syntax} let-syntax ((keyword transformer) ...) exp...
Bind @var{keyword...} to @var{transformer...} while expanding @var{exp...}.
A @code{let-syntax} binding only exists at expansion-time.
@example
(let-syntax ((unless
(syntax-rules ()
((unless condition exp ...)
(if (not condition)
(begin exp ...))))))
(unless #t
(primitive-exit 1))
"rock rock rock")
@result{} "rock rock rock"
@end example
@end deffn
A @code{define-syntax} form is valid anywhere a definition may appear: at the
top-level, or locally. Just as a local @code{define} expands out to an instance
of @code{letrec}, a local @code{define-syntax} expands out to
@code{letrec-syntax}.
@deffn {Syntax} letrec-syntax ((keyword transformer) ...) exp...
Bind @var{keyword...} to @var{transformer...} while expanding @var{exp...}.
In the spirit of @code{letrec} versus @code{let}, an expansion produced by
@var{transformer} may reference a @var{keyword} bound by the
same @var{letrec-syntax}.
@example
(letrec-syntax ((my-or
(syntax-rules ()
((my-or)
#t)
((my-or exp)
exp)
((my-or exp rest ...)
(let ((t exp))
(if exp
exp
(my-or rest ...)))))))
(my-or #f "rockaway beach"))
@result{} "rockaway beach"
@end example
@end deffn
@node Syntax Rules
@subsection Syntax-rules Macros
@code{syntax-rules} macros are simple, pattern-driven syntax transformers, with
a beauty worthy of Scheme.
@deffn {Syntax} syntax-rules literals (pattern template)...
A @code{syntax-rules} macro consists of three parts: the literals (if any), the
patterns, and as many templates as there are patterns.
When the syntax expander sees the invocation of a @code{syntax-rules} macro, it
matches the expression against the patterns, in order, and rewrites the
expression using the template from the first matching pattern. If no pattern
matches, a syntax error is signalled.
@end deffn
@subsubsection Patterns
We have already seen some examples of patterns in the previous section:
@code{(unless condition exp ...)}, @code{(my-or exp)}, and so on. A pattern is
structured like the expression that it is to match. It can have nested structure
as well, like @code{(let ((var val) ...) exp exp* ...)}. Broadly speaking,
patterns are made of lists, improper lists, vectors, identifiers, and datums.
Users can match a sequence of patterns using the ellipsis (@code{...}).
Identifiers in a pattern are called @dfn{literals} if they are present in the
@code{syntax-rules} literals list, and @dfn{pattern variables} otherwise. When
building up the macro output, the expander replaces instances of a pattern
variable in the template with the matched subexpression.
@example
(define-syntax kwote
(syntax-rules ()
((kwote exp)
(quote exp))))
(kwote (foo . bar))
@result{} (foo . bar)
@end example
An improper list of patterns matches as rest arguments do:
@example
(define-syntax let1
(syntax-rules ()
((_ (var val) . exps)
(let ((var val)) . exps))))
@end example
However this definition of @code{let1} probably isn't what you want, as the tail
pattern @var{exps} will match non-lists, like @code{(let1 (foo 'bar) . baz)}. So
often instead of using improper lists as patterns, ellipsized patterns are
better. Instances of a pattern variable in the template must be followed by an
ellipsis.
@example
(define-syntax let1
(syntax-rules ()
((_ (var val) exp ...)
(let ((var val)) exp ...))))
@end example
This @code{let1} probably still doesn't do what we want, because the body
matches sequences of zero expressions, like @code{(let1 (foo 'bar))}. In this
case we need to assert we have at least one body expression. A common idiom for
this is to name the ellipsized pattern variable with an asterisk:
@example
(define-syntax let1
(syntax-rules ()
((_ (var val) exp exp* ...)
(let ((var val)) exp exp* ...))))
@end example
A vector of patterns matches a vector whose contents match the patterns,
including ellipsizing and tail patterns.
@example
(define-syntax letv
(syntax-rules ()
((_ #((var val) ...) exp exp* ...)
(let ((var val) ...) exp exp* ...))))
(letv #((foo 'bar)) foo)
@result{} foo
@end example
Literals are used to match specific datums in an expression, like the use of
@code{=>} and @code{else} in @code{cond} expressions.
@example
(define-syntax cond1
(syntax-rules (=> else)
((cond1 test => fun)
(let ((exp test))
(if exp (fun exp) #f)))
((cond1 test exp exp* ...)
(if test (begin exp exp* ...)))
((cond1 else exp exp* ...)
(begin exp exp* ...))))
(define (square x) (* x x))
(cond1 10 => square)
@result{} 100
(let ((=> #t))
(cond1 10 => square))
@result{} #<procedure square (x)>
@end example
A literal matches an input expression if the input expression is an identifier
with the same name as the literal, and both are unbound@footnote{Language
lawyers probably see the need here for use of @code{literal-identifier=?} rather
than @code{free-identifier=?}, and would probably be correct. Patches
accepted.}.
If a pattern is not a list, vector, or an identifier, it matches as a literal,
with @code{equal?}.
@example
(define-syntax define-matcher-macro
(syntax-rules ()
((_ name lit)
(define-syntax name
(syntax-rules ()
((_ lit) #t)
((_ else) #f))))))
(define-matcher-macro is-literal-foo? "foo")
(is-literal-foo? "foo")
@result{} #t
(is-literal-foo? "bar")
@result{} #f
(let ((foo "foo"))
(is-literal-foo? foo))
@result{} #f
@end example
The last example indicates that matching happens at expansion-time, not
at run-time.
Syntax-rules macros are always used as @code{(@var{macro} . @var{args})}, and
the @var{macro} will always be a symbol. Correspondingly, a @code{syntax-rules}
pattern must be a list (proper or improper), and the first pattern in that list
must be an identifier. Incidentally it can be any identifier -- it doesn't have
to actually be the name of the macro. Thus the following three are equivalent:
@example
(define-syntax when
(syntax-rules ()
((when c e ...)
(if c (begin e ...)))))
(define-syntax when
(syntax-rules ()
((_ c e ...)
(if c (begin e ...)))))
(define-syntax when
(syntax-rules ()
((something-else-entirely c e ...)
(if c (begin e ...)))))
@end example
For clarity, use one of the first two variants. Also note that since the pattern
variable will always match the macro itself (e.g., @code{cond1}), it is actually
left unbound in the template.
@subsubsection Hygiene
@code{syntax-rules} macros have a magical property: they preserve referential
transparency. When you read a macro definition, any free bindings in that macro
are resolved relative to the macro definition; and when you read a macro
instantiation, all free bindings in that expression are resolved relative to the
expression.
This property is sometimes known as @dfn{hygiene}, and it does aid in code
cleanliness. In your macro definitions, you can feel free to introduce temporary
variables, without worrying about inadvertantly introducing bindings into the
macro expansion.
Consider the definition of @code{my-or} from the previous section:
@example
(define-syntax my-or
(syntax-rules ()
((my-or)
#t)
((my-or exp)
exp)
((my-or exp rest ...)
(let ((t exp))
(if exp
exp
(my-or rest ...))))))
@end example
A naive expansion of @code{(let ((t #t)) (my-or #f t))} would yield:
@example
(let ((t #t))
(let ((t #f))
(if t t t)))
@result{} #f
@end example
@noindent
Which clearly is not what we want. Somehow the @code{t} in the definition is
distinct from the @code{t} at the site of use; and it is indeed this distinction
that is maintained by the syntax expander, when expanding hygienic macros.
This discussion is mostly relevant in the context of traditional Lisp macros
(@pxref{Defmacros}), which do not preserve referential transparency. Hygiene
adds to the expressive power of Scheme.
@subsubsection Further Information
For a formal definition of @code{syntax-rules} and its pattern language, see
@xref{Macros, , Macros, r5rs, Revised(5) Report on the Algorithmic Language
Scheme}.
@code{syntax-rules} macros are simple and clean, but do they have limitations.
They do not lend themselves to expressive error messages: patterns either match
or they don't. Their ability to generate code is limited to template-driven
expansion; often one needs to define a number of helper macros to get real work
done. Sometimes one wants to introduce a binding into the lexical context of the
generated code; this is impossible with @code{syntax-rules}. Relatedly, they
cannot programmatically generate identifiers.
The solution to all of these problems is to use @code{syntax-case} if you need
its features. But if for some reason you're stuck with @code{syntax-rules}, you
might enjoy Joe Marshall's
@uref{http://sites.google.com/site/evalapply/eccentric.txt,@code{syntax-rules}
Primer for the Merely Eccentric}.
@node Syntax Case
@subsection Support for the @code{syntax-case} System
@node Defmacros
@subsection Lisp-style Macro Definitions
In Lisp-like languages, the traditional way to define macros is very
similar to procedure definitions. The key differences are that the
macro definition body should return a list that describes the
transformed expression, and that the definition is marked as a macro
definition (rather than a procedure definition) by the use of a
different definition keyword: in Lisp, @code{defmacro} rather than
@code{defun}, and in Scheme, @code{define-macro} rather than
@code{define}.
@fnindex defmacro
@fnindex define-macro
Guile supports this style of macro definition using both @code{defmacro}
and @code{define-macro}. The only difference between them is how the
macro name and arguments are grouped together in the definition:
@lisp
(defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
@end lisp
@noindent
is the same as
@lisp
(define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
@end lisp
@noindent
The difference is analogous to the corresponding difference between
Lisp's @code{defun} and Scheme's @code{define}.
@code{false-if-exception}, from the @file{boot-9.scm} file in the Guile
distribution, is a good example of macro definition using
@code{defmacro}:
@lisp
(defmacro false-if-exception (expr)
`(catch #t
(lambda () ,expr)
(lambda args #f)))
@end lisp
@noindent
The effect of this definition is that expressions beginning with the
identifier @code{false-if-exception} are automatically transformed into
a @code{catch} expression following the macro definition specification.
For example:
@lisp
(false-if-exception (open-input-file "may-not-exist"))
@equiv{}
(catch #t
(lambda () (open-input-file "may-not-exist"))
(lambda args #f))
@end lisp
@deffn {Scheme Procedure} cons-source xorig x y
@deffnx {C Function} scm_cons_source (xorig, x, y)
Create and return a new pair whose car and cdr are @var{x} and @var{y}.
Any source properties associated with @var{xorig} are also associated
with the new pair.
@end deffn
@node Identifier Macros
@subsection Identifier Macros
@node Eval When
@subsection Eval-when
@node Internal Macros
@subsection Internal Macros
Internally, Guile represents macros using a disjoint type.
@deffn {Scheme Procedure} make-syntax-transformer name type binding
@end deffn
@deffn {Scheme Procedure} macro? obj
@deffnx {C Function} scm_macro_p (obj)
Return @code{#t} if @var{obj} is a regular macro, a memoizing macro, a
syntax transformer, or a syntax-case macro.
@end deffn
@deffn {Scheme Procedure} macro-type m
@deffnx {C Function} scm_macro_type (m)
Return one of the symbols @code{syntax}, @code{macro},
@code{macro!}, or @code{syntax-case}, depending on whether
@var{m} is a syntax transformer, a regular macro, a memoizing
macro, or a syntax-case macro, respectively. If @var{m} is
not a macro, @code{#f} is returned.
@end deffn
@deffn {Scheme Procedure} macro-name m
@deffnx {C Function} scm_macro_name (m)
Return the name of the macro @var{m}.
@end deffn
@deffn {Scheme Procedure} macro-transformer m
@deffnx {C Function} scm_macro_transformer (m)
Return the transformer of the macro @var{m}.
@end deffn
@deffn {Scheme Procedure} macro-binding m
@deffnx {C Function} scm_macro_binding (m)
Return the binding of the macro @var{m}.
@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
|