Commit | Line | Data |
---|---|---|
e4955559 AW |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
2d6a3144 MW |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2011, |
4 | @c 2012, 2013, 2014 Free Software Foundation, Inc. | |
e4955559 AW |
5 | @c See the file guile.texi for copying conditions. |
6 | ||
e4955559 AW |
7 | @node Macros |
8 | @section Macros | |
9 | ||
10 | At its best, programming in Lisp is an iterative process of building up a | |
11 | language appropriate to the problem at hand, and then solving the problem in | |
12 | that language. Defining new procedures is part of that, but Lisp also allows | |
13 | the user to extend its syntax, with its famous @dfn{macros}. | |
14 | ||
15 | @cindex macros | |
16 | @cindex transformation | |
17 | Macros are syntactic extensions which cause the expression that they appear in | |
18 | to be transformed in some way @emph{before} being evaluated. In expressions that | |
19 | are intended for macro transformation, the identifier that names the relevant | |
20 | macro must appear as the first element, like this: | |
21 | ||
22 | @lisp | |
23 | (@var{macro-name} @var{macro-args} @dots{}) | |
24 | @end lisp | |
25 | ||
26 | @cindex macro expansion | |
cf14f301 LC |
27 | @cindex domain-specific language |
28 | @cindex embedded domain-specific language | |
29 | @cindex DSL | |
30 | @cindex EDSL | |
e4955559 AW |
31 | Macro expansion is a separate phase of evaluation, run before code is |
32 | interpreted or compiled. A macro is a program that runs on programs, translating | |
cf14f301 LC |
33 | an embedded language into core Scheme@footnote{These days such embedded |
34 | languages are often referred to as @dfn{embedded domain-specific | |
35 | languages}, or EDSLs.}. | |
e4955559 AW |
36 | |
37 | @menu | |
38 | * Defining Macros:: Binding macros, globally and locally. | |
39 | * Syntax Rules:: Pattern-driven macros. | |
40 | * Syntax Case:: Procedural, hygienic macros. | |
9b0975f1 | 41 | * Syntax Transformer Helpers:: Helpers for use in procedural macros. |
e4955559 AW |
42 | * Defmacros:: Lisp-style macros. |
43 | * Identifier Macros:: Identifier macros. | |
9b0975f1 | 44 | * Syntax Parameters:: Syntax Parameters. |
e4955559 | 45 | * Eval When:: Affecting the expand-time environment. |
67915ab0 | 46 | * Macro Expansion:: Procedurally expanding macros. |
03dfed84 | 47 | * Hygiene and the Top-Level:: A hack you might want to know about. |
e4955559 AW |
48 | * Internal Macros:: Macros as first-class values. |
49 | @end menu | |
50 | ||
51 | @node Defining Macros | |
52 | @subsection Defining Macros | |
53 | ||
54 | A macro is a binding between a keyword and a syntax transformer. Since it's | |
55 | difficult to discuss @code{define-syntax} without discussing the format of | |
56 | transformers, consider the following example macro definition: | |
57 | ||
58 | @example | |
59 | (define-syntax when | |
60 | (syntax-rules () | |
61 | ((when condition exp ...) | |
62 | (if condition | |
63 | (begin exp ...))))) | |
64 | ||
65 | (when #t | |
66 | (display "hey ho\n") | |
67 | (display "let's go\n")) | |
68 | @print{} hey ho | |
69 | @print{} let's go | |
70 | @end example | |
71 | ||
72 | In this example, the @code{when} binding is bound with @code{define-syntax}. | |
73 | Syntax transformers are discussed in more depth in @ref{Syntax Rules} and | |
74 | @ref{Syntax Case}. | |
75 | ||
76 | @deffn {Syntax} define-syntax keyword transformer | |
77 | Bind @var{keyword} to the syntax transformer obtained by evaluating | |
78 | @var{transformer}. | |
79 | ||
80 | After a macro has been defined, further instances of @var{keyword} in Scheme | |
81 | source code will invoke the syntax transformer defined by @var{transformer}. | |
82 | @end deffn | |
83 | ||
84 | One can also establish local syntactic bindings with @code{let-syntax}. | |
85 | ||
df0a1002 BT |
86 | @deffn {Syntax} let-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{} |
87 | Bind each @var{keyword} to its corresponding @var{transformer} while | |
88 | expanding @var{exp1} @var{exp2} @enddots{}. | |
e4955559 AW |
89 | |
90 | A @code{let-syntax} binding only exists at expansion-time. | |
91 | ||
92 | @example | |
93 | (let-syntax ((unless | |
94 | (syntax-rules () | |
95 | ((unless condition exp ...) | |
96 | (if (not condition) | |
97 | (begin exp ...)))))) | |
98 | (unless #t | |
99 | (primitive-exit 1)) | |
100 | "rock rock rock") | |
101 | @result{} "rock rock rock" | |
102 | @end example | |
103 | @end deffn | |
104 | ||
105 | A @code{define-syntax} form is valid anywhere a definition may appear: at the | |
106 | top-level, or locally. Just as a local @code{define} expands out to an instance | |
107 | of @code{letrec}, a local @code{define-syntax} expands out to | |
108 | @code{letrec-syntax}. | |
109 | ||
df0a1002 BT |
110 | @deffn {Syntax} letrec-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{} |
111 | Bind each @var{keyword} to its corresponding @var{transformer} while | |
112 | expanding @var{exp1} @var{exp2} @enddots{}. | |
e4955559 AW |
113 | |
114 | In the spirit of @code{letrec} versus @code{let}, an expansion produced by | |
115 | @var{transformer} may reference a @var{keyword} bound by the | |
116 | same @var{letrec-syntax}. | |
117 | ||
118 | @example | |
119 | (letrec-syntax ((my-or | |
120 | (syntax-rules () | |
121 | ((my-or) | |
122 | #t) | |
123 | ((my-or exp) | |
124 | exp) | |
125 | ((my-or exp rest ...) | |
126 | (let ((t exp)) | |
e006d87b MW |
127 | (if t |
128 | t | |
e4955559 AW |
129 | (my-or rest ...))))))) |
130 | (my-or #f "rockaway beach")) | |
131 | @result{} "rockaway beach" | |
132 | @end example | |
133 | @end deffn | |
134 | ||
135 | @node Syntax Rules | |
136 | @subsection Syntax-rules Macros | |
137 | ||
138 | @code{syntax-rules} macros are simple, pattern-driven syntax transformers, with | |
139 | a beauty worthy of Scheme. | |
140 | ||
1624e149 | 141 | @deffn {Syntax} syntax-rules literals (pattern template) @dots{} |
1fc8dcc7 AW |
142 | Create a syntax transformer that will rewrite an expression using the rules |
143 | embodied in the @var{pattern} and @var{template} clauses. | |
144 | @end deffn | |
145 | ||
e4955559 AW |
146 | A @code{syntax-rules} macro consists of three parts: the literals (if any), the |
147 | patterns, and as many templates as there are patterns. | |
148 | ||
149 | When the syntax expander sees the invocation of a @code{syntax-rules} macro, it | |
150 | matches the expression against the patterns, in order, and rewrites the | |
151 | expression using the template from the first matching pattern. If no pattern | |
152 | matches, a syntax error is signalled. | |
e4955559 AW |
153 | |
154 | @subsubsection Patterns | |
155 | ||
156 | We have already seen some examples of patterns in the previous section: | |
157 | @code{(unless condition exp ...)}, @code{(my-or exp)}, and so on. A pattern is | |
158 | structured like the expression that it is to match. It can have nested structure | |
159 | as well, like @code{(let ((var val) ...) exp exp* ...)}. Broadly speaking, | |
160 | patterns are made of lists, improper lists, vectors, identifiers, and datums. | |
161 | Users can match a sequence of patterns using the ellipsis (@code{...}). | |
162 | ||
163 | Identifiers in a pattern are called @dfn{literals} if they are present in the | |
164 | @code{syntax-rules} literals list, and @dfn{pattern variables} otherwise. When | |
165 | building up the macro output, the expander replaces instances of a pattern | |
166 | variable in the template with the matched subexpression. | |
167 | ||
168 | @example | |
169 | (define-syntax kwote | |
170 | (syntax-rules () | |
171 | ((kwote exp) | |
172 | (quote exp)))) | |
173 | (kwote (foo . bar)) | |
174 | @result{} (foo . bar) | |
175 | @end example | |
176 | ||
177 | An improper list of patterns matches as rest arguments do: | |
178 | ||
179 | @example | |
180 | (define-syntax let1 | |
181 | (syntax-rules () | |
182 | ((_ (var val) . exps) | |
183 | (let ((var val)) . exps)))) | |
184 | @end example | |
185 | ||
186 | However this definition of @code{let1} probably isn't what you want, as the tail | |
187 | pattern @var{exps} will match non-lists, like @code{(let1 (foo 'bar) . baz)}. So | |
188 | often instead of using improper lists as patterns, ellipsized patterns are | |
189 | better. Instances of a pattern variable in the template must be followed by an | |
190 | ellipsis. | |
191 | ||
192 | @example | |
193 | (define-syntax let1 | |
194 | (syntax-rules () | |
195 | ((_ (var val) exp ...) | |
196 | (let ((var val)) exp ...)))) | |
197 | @end example | |
198 | ||
199 | This @code{let1} probably still doesn't do what we want, because the body | |
200 | matches sequences of zero expressions, like @code{(let1 (foo 'bar))}. In this | |
201 | case we need to assert we have at least one body expression. A common idiom for | |
202 | this is to name the ellipsized pattern variable with an asterisk: | |
203 | ||
204 | @example | |
205 | (define-syntax let1 | |
206 | (syntax-rules () | |
207 | ((_ (var val) exp exp* ...) | |
208 | (let ((var val)) exp exp* ...)))) | |
209 | @end example | |
210 | ||
211 | A vector of patterns matches a vector whose contents match the patterns, | |
212 | including ellipsizing and tail patterns. | |
213 | ||
214 | @example | |
215 | (define-syntax letv | |
216 | (syntax-rules () | |
217 | ((_ #((var val) ...) exp exp* ...) | |
218 | (let ((var val) ...) exp exp* ...)))) | |
219 | (letv #((foo 'bar)) foo) | |
912f5f34 | 220 | @result{} bar |
e4955559 AW |
221 | @end example |
222 | ||
223 | Literals are used to match specific datums in an expression, like the use of | |
224 | @code{=>} and @code{else} in @code{cond} expressions. | |
225 | ||
226 | @example | |
227 | (define-syntax cond1 | |
228 | (syntax-rules (=> else) | |
229 | ((cond1 test => fun) | |
230 | (let ((exp test)) | |
231 | (if exp (fun exp) #f))) | |
232 | ((cond1 test exp exp* ...) | |
233 | (if test (begin exp exp* ...))) | |
234 | ((cond1 else exp exp* ...) | |
235 | (begin exp exp* ...)))) | |
236 | ||
237 | (define (square x) (* x x)) | |
238 | (cond1 10 => square) | |
239 | @result{} 100 | |
240 | (let ((=> #t)) | |
241 | (cond1 10 => square)) | |
242 | @result{} #<procedure square (x)> | |
243 | @end example | |
244 | ||
245 | A literal matches an input expression if the input expression is an identifier | |
246 | with the same name as the literal, and both are unbound@footnote{Language | |
247 | lawyers probably see the need here for use of @code{literal-identifier=?} rather | |
248 | than @code{free-identifier=?}, and would probably be correct. Patches | |
249 | accepted.}. | |
250 | ||
251 | If a pattern is not a list, vector, or an identifier, it matches as a literal, | |
252 | with @code{equal?}. | |
253 | ||
254 | @example | |
255 | (define-syntax define-matcher-macro | |
256 | (syntax-rules () | |
257 | ((_ name lit) | |
258 | (define-syntax name | |
259 | (syntax-rules () | |
260 | ((_ lit) #t) | |
261 | ((_ else) #f)))))) | |
262 | ||
263 | (define-matcher-macro is-literal-foo? "foo") | |
264 | ||
265 | (is-literal-foo? "foo") | |
266 | @result{} #t | |
267 | (is-literal-foo? "bar") | |
268 | @result{} #f | |
269 | (let ((foo "foo")) | |
270 | (is-literal-foo? foo)) | |
271 | @result{} #f | |
272 | @end example | |
273 | ||
274 | The last example indicates that matching happens at expansion-time, not | |
275 | at run-time. | |
276 | ||
277 | Syntax-rules macros are always used as @code{(@var{macro} . @var{args})}, and | |
278 | the @var{macro} will always be a symbol. Correspondingly, a @code{syntax-rules} | |
279 | pattern must be a list (proper or improper), and the first pattern in that list | |
280 | must be an identifier. Incidentally it can be any identifier -- it doesn't have | |
281 | to actually be the name of the macro. Thus the following three are equivalent: | |
282 | ||
283 | @example | |
284 | (define-syntax when | |
285 | (syntax-rules () | |
286 | ((when c e ...) | |
287 | (if c (begin e ...))))) | |
288 | ||
289 | (define-syntax when | |
290 | (syntax-rules () | |
291 | ((_ c e ...) | |
292 | (if c (begin e ...))))) | |
293 | ||
294 | (define-syntax when | |
295 | (syntax-rules () | |
296 | ((something-else-entirely c e ...) | |
297 | (if c (begin e ...))))) | |
298 | @end example | |
299 | ||
300 | For clarity, use one of the first two variants. Also note that since the pattern | |
301 | variable will always match the macro itself (e.g., @code{cond1}), it is actually | |
302 | left unbound in the template. | |
303 | ||
304 | @subsubsection Hygiene | |
305 | ||
306 | @code{syntax-rules} macros have a magical property: they preserve referential | |
307 | transparency. When you read a macro definition, any free bindings in that macro | |
308 | are resolved relative to the macro definition; and when you read a macro | |
309 | instantiation, all free bindings in that expression are resolved relative to the | |
310 | expression. | |
311 | ||
312 | This property is sometimes known as @dfn{hygiene}, and it does aid in code | |
313 | cleanliness. In your macro definitions, you can feel free to introduce temporary | |
ecb87335 | 314 | variables, without worrying about inadvertently introducing bindings into the |
e4955559 AW |
315 | macro expansion. |
316 | ||
317 | Consider the definition of @code{my-or} from the previous section: | |
318 | ||
319 | @example | |
320 | (define-syntax my-or | |
321 | (syntax-rules () | |
322 | ((my-or) | |
323 | #t) | |
324 | ((my-or exp) | |
325 | exp) | |
326 | ((my-or exp rest ...) | |
327 | (let ((t exp)) | |
e006d87b MW |
328 | (if t |
329 | t | |
e4955559 AW |
330 | (my-or rest ...)))))) |
331 | @end example | |
332 | ||
333 | A naive expansion of @code{(let ((t #t)) (my-or #f t))} would yield: | |
334 | ||
335 | @example | |
336 | (let ((t #t)) | |
337 | (let ((t #f)) | |
338 | (if t t t))) | |
339 | @result{} #f | |
340 | @end example | |
341 | ||
342 | @noindent | |
343 | Which clearly is not what we want. Somehow the @code{t} in the definition is | |
344 | distinct from the @code{t} at the site of use; and it is indeed this distinction | |
345 | that is maintained by the syntax expander, when expanding hygienic macros. | |
346 | ||
347 | This discussion is mostly relevant in the context of traditional Lisp macros | |
348 | (@pxref{Defmacros}), which do not preserve referential transparency. Hygiene | |
349 | adds to the expressive power of Scheme. | |
350 | ||
cd4171d0 AW |
351 | @subsubsection Shorthands |
352 | ||
353 | One often ends up writing simple one-clause @code{syntax-rules} macros. | |
354 | There is a convenient shorthand for this idiom, in the form of | |
355 | @code{define-syntax-rule}. | |
356 | ||
357 | @deffn {Syntax} define-syntax-rule (keyword . pattern) [docstring] template | |
358 | Define @var{keyword} as a new @code{syntax-rules} macro with one clause. | |
359 | @end deffn | |
360 | ||
361 | Cast into this form, our @code{when} example is significantly shorter: | |
362 | ||
363 | @example | |
364 | (define-syntax-rule (when c e ...) | |
365 | (if c (begin e ...))) | |
366 | @end example | |
367 | ||
0e181633 MW |
368 | @subsubsection Reporting Syntax Errors in Macros |
369 | ||
370 | @deffn {Syntax} syntax-error message [arg ...] | |
371 | Report an error at macro-expansion time. @var{message} must be a string | |
372 | literal, and the optional @var{arg} operands can be arbitrary expressions | |
373 | providing additional information. | |
374 | @end deffn | |
375 | ||
376 | @code{syntax-error} is intended to be used within @code{syntax-rules} | |
377 | templates. For example: | |
378 | ||
379 | @example | |
380 | (define-syntax simple-let | |
381 | (syntax-rules () | |
382 | ((_ (head ... ((x . y) val) . tail) | |
383 | body1 body2 ...) | |
384 | (syntax-error | |
385 | "expected an identifier but got" | |
386 | (x . y))) | |
387 | ((_ ((name val) ...) body1 body2 ...) | |
388 | ((lambda (name ...) body1 body2 ...) | |
389 | val ...)))) | |
390 | @end example | |
391 | ||
1624e149 MW |
392 | @subsubsection Specifying a Custom Ellipsis Identifier |
393 | ||
394 | When writing macros that generate macro definitions, it is convenient to | |
395 | use a different ellipsis identifier at each level. Guile allows the | |
396 | desired ellipsis identifier to be specified as the first operand to | |
2d6a3144 | 397 | @code{syntax-rules}, as specified by SRFI-46 and R7RS. For example: |
1624e149 MW |
398 | |
399 | @example | |
400 | (define-syntax define-quotation-macros | |
401 | (syntax-rules () | |
402 | ((_ (macro-name head-symbol) ...) | |
403 | (begin (define-syntax macro-name | |
404 | (syntax-rules ::: () | |
405 | ((_ x :::) | |
406 | (quote (head-symbol x :::))))) | |
407 | ...)))) | |
408 | (define-quotation-macros (quote-a a) (quote-b b) (quote-c c)) | |
409 | (quote-a 1 2 3) @result{} (a 1 2 3) | |
410 | @end example | |
411 | ||
e4955559 AW |
412 | @subsubsection Further Information |
413 | ||
414 | For a formal definition of @code{syntax-rules} and its pattern language, see | |
415 | @xref{Macros, , Macros, r5rs, Revised(5) Report on the Algorithmic Language | |
416 | Scheme}. | |
417 | ||
418 | @code{syntax-rules} macros are simple and clean, but do they have limitations. | |
419 | They do not lend themselves to expressive error messages: patterns either match | |
420 | or they don't. Their ability to generate code is limited to template-driven | |
421 | expansion; often one needs to define a number of helper macros to get real work | |
422 | done. Sometimes one wants to introduce a binding into the lexical context of the | |
423 | generated code; this is impossible with @code{syntax-rules}. Relatedly, they | |
424 | cannot programmatically generate identifiers. | |
425 | ||
426 | The solution to all of these problems is to use @code{syntax-case} if you need | |
427 | its features. But if for some reason you're stuck with @code{syntax-rules}, you | |
428 | might enjoy Joe Marshall's | |
429 | @uref{http://sites.google.com/site/evalapply/eccentric.txt,@code{syntax-rules} | |
430 | Primer for the Merely Eccentric}. | |
431 | ||
432 | @node Syntax Case | |
433 | @subsection Support for the @code{syntax-case} System | |
434 | ||
1fc8dcc7 AW |
435 | @code{syntax-case} macros are procedural syntax transformers, with a power |
436 | worthy of Scheme. | |
437 | ||
1624e149 | 438 | @deffn {Syntax} syntax-case syntax literals (pattern [guard] exp) @dots{} |
1fc8dcc7 AW |
439 | Match the syntax object @var{syntax} against the given patterns, in order. If a |
440 | @var{pattern} matches, return the result of evaluating the associated @var{exp}. | |
441 | @end deffn | |
442 | ||
443 | Compare the following definitions of @code{when}: | |
444 | ||
445 | @example | |
446 | (define-syntax when | |
447 | (syntax-rules () | |
448 | ((_ test e e* ...) | |
449 | (if test (begin e e* ...))))) | |
450 | ||
451 | (define-syntax when | |
452 | (lambda (x) | |
453 | (syntax-case x () | |
454 | ((_ test e e* ...) | |
455 | #'(if test (begin e e* ...)))))) | |
456 | @end example | |
457 | ||
458 | Clearly, the @code{syntax-case} definition is similar to its @code{syntax-rules} | |
459 | counterpart, and equally clearly there are some differences. The | |
460 | @code{syntax-case} definition is wrapped in a @code{lambda}, a function of one | |
461 | argument; that argument is passed to the @code{syntax-case} invocation; and the | |
462 | ``return value'' of the macro has a @code{#'} prefix. | |
463 | ||
464 | All of these differences stem from the fact that @code{syntax-case} does not | |
465 | define a syntax transformer itself -- instead, @code{syntax-case} expressions | |
466 | provide a way to destructure a @dfn{syntax object}, and to rebuild syntax | |
467 | objects as output. | |
468 | ||
469 | So the @code{lambda} wrapper is simply a leaky implementation detail, that | |
470 | syntax transformers are just functions that transform syntax to syntax. This | |
471 | should not be surprising, given that we have already described macros as | |
472 | ``programs that write programs''. @code{syntax-case} is simply a way to take | |
473 | apart and put together program text, and to be a valid syntax transformer it | |
474 | needs to be wrapped in a procedure. | |
475 | ||
476 | Unlike traditional Lisp macros (@pxref{Defmacros}), @code{syntax-case} macros | |
477 | transform syntax objects, not raw Scheme forms. Recall the naive expansion of | |
478 | @code{my-or} given in the previous section: | |
479 | ||
480 | @example | |
481 | (let ((t #t)) | |
482 | (my-or #f t)) | |
483 | ;; naive expansion: | |
484 | (let ((t #t)) | |
485 | (let ((t #f)) | |
486 | (if t t t))) | |
487 | @end example | |
488 | ||
489 | Raw Scheme forms simply don't have enough information to distinguish the first | |
490 | two @code{t} instances in @code{(if t t t)} from the third @code{t}. So instead | |
491 | of representing identifiers as symbols, the syntax expander represents | |
492 | identifiers as annotated syntax objects, attaching such information to those | |
493 | syntax objects as is needed to maintain referential transparency. | |
494 | ||
495 | @deffn {Syntax} syntax form | |
496 | Create a syntax object wrapping @var{form} within the current lexical context. | |
497 | @end deffn | |
498 | ||
499 | Syntax objects are typically created internally to the process of expansion, but | |
500 | it is possible to create them outside of syntax expansion: | |
501 | ||
502 | @example | |
503 | (syntax (foo bar baz)) | |
504 | @result{} #<some representation of that syntax> | |
505 | @end example | |
506 | ||
507 | @noindent | |
508 | However it is more common, and useful, to create syntax objects when building | |
509 | output from a @code{syntax-case} expression. | |
510 | ||
511 | @example | |
512 | (define-syntax add1 | |
513 | (lambda (x) | |
514 | (syntax-case x () | |
515 | ((_ exp) | |
516 | (syntax (+ exp 1)))))) | |
517 | @end example | |
518 | ||
519 | It is not strictly necessary for a @code{syntax-case} expression to return a | |
520 | syntax object, because @code{syntax-case} expressions can be used in helper | |
521 | functions, or otherwise used outside of syntax expansion itself. However a | |
7545ddd4 | 522 | syntax transformer procedure must return a syntax object, so most uses of |
1fc8dcc7 AW |
523 | @code{syntax-case} do end up returning syntax objects. |
524 | ||
525 | Here in this case, the form that built the return value was @code{(syntax (+ exp | |
526 | 1))}. The interesting thing about this is that within a @code{syntax} | |
7545ddd4 | 527 | expression, any appearance of a pattern variable is substituted into the |
1fc8dcc7 AW |
528 | resulting syntax object, carrying with it all relevant metadata from the source |
529 | expression, such as lexical identity and source location. | |
530 | ||
531 | Indeed, a pattern variable may only be referenced from inside a @code{syntax} | |
532 | form. The syntax expander would raise an error when defining @code{add1} if it | |
533 | found @var{exp} referenced outside a @code{syntax} form. | |
534 | ||
535 | Since @code{syntax} appears frequently in macro-heavy code, it has a special | |
536 | reader macro: @code{#'}. @code{#'foo} is transformed by the reader into | |
ecb87335 | 537 | @code{(syntax foo)}, just as @code{'foo} is transformed into @code{(quote foo)}. |
1fc8dcc7 AW |
538 | |
539 | The pattern language used by @code{syntax-case} is conveniently the same | |
540 | language used by @code{syntax-rules}. Given this, Guile actually defines | |
541 | @code{syntax-rules} in terms of @code{syntax-case}: | |
542 | ||
543 | @example | |
544 | (define-syntax syntax-rules | |
545 | (lambda (x) | |
546 | (syntax-case x () | |
547 | ((_ (k ...) ((keyword . pattern) template) ...) | |
548 | #'(lambda (x) | |
549 | (syntax-case x (k ...) | |
550 | ((dummy . pattern) #'template) | |
551 | ...)))))) | |
552 | @end example | |
553 | ||
554 | And that's that. | |
555 | ||
556 | @subsubsection Why @code{syntax-case}? | |
557 | ||
558 | The examples we have shown thus far could just as well have been expressed with | |
559 | @code{syntax-rules}, and have just shown that @code{syntax-case} is more | |
560 | verbose, which is true. But there is a difference: @code{syntax-case} creates | |
561 | @emph{procedural} macros, giving the full power of Scheme to the macro expander. | |
562 | This has many practical applications. | |
563 | ||
564 | A common desire is to be able to match a form only if it is an identifier. This | |
565 | is impossible with @code{syntax-rules}, given the datum matching forms. But with | |
566 | @code{syntax-case} it is easy: | |
567 | ||
568 | @deffn {Scheme Procedure} identifier? syntax-object | |
a4b4fbbd JE |
569 | Returns @code{#t} if @var{syntax-object} is an identifier, or @code{#f} |
570 | otherwise. | |
1fc8dcc7 AW |
571 | @end deffn |
572 | ||
573 | @example | |
7545ddd4 | 574 | ;; relying on previous add1 definition |
1fc8dcc7 AW |
575 | (define-syntax add1! |
576 | (lambda (x) | |
577 | (syntax-case x () | |
578 | ((_ var) (identifier? #'var) | |
579 | #'(set! var (add1 var)))))) | |
580 | ||
581 | (define foo 0) | |
582 | (add1! foo) | |
583 | foo @result{} 1 | |
584 | (add1! "not-an-identifier") @result{} error | |
585 | @end example | |
586 | ||
587 | With @code{syntax-rules}, the error for @code{(add1! "not-an-identifier")} would | |
588 | be something like ``invalid @code{set!}''. With @code{syntax-case}, it will say | |
589 | something like ``invalid @code{add1!}'', because we attach the @dfn{guard | |
590 | clause} to the pattern: @code{(identifier? #'var)}. This becomes more important | |
591 | with more complicated macros. It is necessary to use @code{identifier?}, because | |
592 | to the expander, an identifier is more than a bare symbol. | |
593 | ||
594 | Note that even in the guard clause, we reference the @var{var} pattern variable | |
595 | within a @code{syntax} form, via @code{#'var}. | |
596 | ||
597 | Another common desire is to introduce bindings into the lexical context of the | |
598 | output expression. One example would be in the so-called ``anaphoric macros'', | |
599 | like @code{aif}. Anaphoric macros bind some expression to a well-known | |
600 | identifier, often @code{it}, within their bodies. For example, in @code{(aif | |
601 | (foo) (bar it))}, @code{it} would be bound to the result of @code{(foo)}. | |
602 | ||
603 | To begin with, we should mention a solution that doesn't work: | |
604 | ||
605 | @example | |
606 | ;; doesn't work | |
607 | (define-syntax aif | |
608 | (lambda (x) | |
609 | (syntax-case x () | |
610 | ((_ test then else) | |
611 | #'(let ((it test)) | |
612 | (if it then else)))))) | |
613 | @end example | |
614 | ||
615 | The reason that this doesn't work is that, by default, the expander will | |
616 | preserve referential transparency; the @var{then} and @var{else} expressions | |
617 | won't have access to the binding of @code{it}. | |
618 | ||
619 | But they can, if we explicitly introduce a binding via @code{datum->syntax}. | |
620 | ||
621 | @deffn {Scheme Procedure} datum->syntax for-syntax datum | |
622 | Create a syntax object that wraps @var{datum}, within the lexical context | |
623 | corresponding to the syntax object @var{for-syntax}. | |
624 | @end deffn | |
625 | ||
626 | For completeness, we should mention that it is possible to strip the metadata | |
627 | from a syntax object, returning a raw Scheme datum: | |
628 | ||
629 | @deffn {Scheme Procedure} syntax->datum syntax-object | |
630 | Strip the metadata from @var{syntax-object}, returning its contents as a raw | |
631 | Scheme datum. | |
632 | @end deffn | |
633 | ||
634 | In this case we want to introduce @code{it} in the context of the whole | |
635 | expression, so we can create a syntax object as @code{(datum->syntax x 'it)}, | |
636 | where @code{x} is the whole expression, as passed to the transformer procedure. | |
637 | ||
638 | Here's another solution that doesn't work: | |
639 | ||
640 | @example | |
641 | ;; doesn't work either | |
642 | (define-syntax aif | |
643 | (lambda (x) | |
644 | (syntax-case x () | |
645 | ((_ test then else) | |
646 | (let ((it (datum->syntax x 'it))) | |
647 | #'(let ((it test)) | |
648 | (if it then else))))))) | |
649 | @end example | |
650 | ||
09cb3ae2 NL |
651 | The reason that this one doesn't work is that there are really two |
652 | environments at work here -- the environment of pattern variables, as | |
653 | bound by @code{syntax-case}, and the environment of lexical variables, | |
654 | as bound by normal Scheme. The outer let form establishes a binding in | |
655 | the environment of lexical variables, but the inner let form is inside a | |
656 | syntax form, where only pattern variables will be substituted. Here we | |
657 | need to introduce a piece of the lexical environment into the pattern | |
658 | variable environment, and we can do so using @code{syntax-case} itself: | |
1fc8dcc7 AW |
659 | |
660 | @example | |
661 | ;; works, but is obtuse | |
662 | (define-syntax aif | |
663 | (lambda (x) | |
664 | (syntax-case x () | |
665 | ((_ test then else) | |
666 | ;; invoking syntax-case on the generated | |
667 | ;; syntax object to expose it to `syntax' | |
668 | (syntax-case (datum->syntax x 'it) () | |
669 | (it | |
670 | #'(let ((it test)) | |
671 | (if it then else)))))))) | |
672 | ||
673 | (aif (getuid) (display it) (display "none")) (newline) | |
674 | @print{} 500 | |
675 | @end example | |
676 | ||
677 | However there are easier ways to write this. @code{with-syntax} is often | |
678 | convenient: | |
679 | ||
1624e149 | 680 | @deffn {Syntax} with-syntax ((pat val) @dots{}) exp @dots{} |
1fc8dcc7 | 681 | Bind patterns @var{pat} from their corresponding values @var{val}, within the |
1624e149 | 682 | lexical context of @var{exp} @enddots{}. |
1fc8dcc7 AW |
683 | |
684 | @example | |
685 | ;; better | |
686 | (define-syntax aif | |
687 | (lambda (x) | |
688 | (syntax-case x () | |
689 | ((_ test then else) | |
690 | (with-syntax ((it (datum->syntax x 'it))) | |
691 | #'(let ((it test)) | |
692 | (if it then else))))))) | |
693 | @end example | |
694 | @end deffn | |
695 | ||
696 | As you might imagine, @code{with-syntax} is defined in terms of | |
697 | @code{syntax-case}. But even that might be off-putting to you if you are an old | |
698 | Lisp macro hacker, used to building macro output with @code{quasiquote}. The | |
699 | issue is that @code{with-syntax} creates a separation between the point of | |
700 | definition of a value and its point of substitution. | |
701 | ||
702 | @pindex quasisyntax | |
703 | @pindex unsyntax | |
704 | @pindex unsyntax-splicing | |
705 | So for cases in which a @code{quasiquote} style makes more sense, | |
706 | @code{syntax-case} also defines @code{quasisyntax}, and the related | |
707 | @code{unsyntax} and @code{unsyntax-splicing}, abbreviated by the reader as | |
708 | @code{#`}, @code{#,}, and @code{#,@@}, respectively. | |
709 | ||
710 | For example, to define a macro that inserts a compile-time timestamp into a | |
711 | source file, one may write: | |
712 | ||
713 | @example | |
714 | (define-syntax display-compile-timestamp | |
715 | (lambda (x) | |
716 | (syntax-case x () | |
717 | ((_) | |
718 | #`(begin | |
719 | (display "The compile timestamp was: ") | |
720 | (display #,(current-time)) | |
721 | (newline)))))) | |
722 | @end example | |
723 | ||
9b0975f1 AW |
724 | Readers interested in further information on @code{syntax-case} macros should |
725 | see R. Kent Dybvig's excellent @cite{The Scheme Programming Language}, either | |
726 | edition 3 or 4, in the chapter on syntax. Dybvig was the primary author of the | |
727 | @code{syntax-case} system. The book itself is available online at | |
728 | @uref{http://scheme.com/tspl4/}. | |
729 | ||
1624e149 MW |
730 | @subsubsection Custom Ellipsis Identifiers for syntax-case Macros |
731 | ||
732 | When writing procedural macros that generate macro definitions, it is | |
733 | convenient to use a different ellipsis identifier at each level. Guile | |
734 | supports this for procedural macros using the @code{with-ellipsis} | |
735 | special form: | |
736 | ||
737 | @deffn {Syntax} with-ellipsis ellipsis body @dots{} | |
738 | @var{ellipsis} must be an identifier. Evaluate @var{body} in a special | |
739 | lexical environment such that all macro patterns and templates within | |
740 | @var{body} will use @var{ellipsis} as the ellipsis identifier instead of | |
741 | the usual three dots (@code{...}). | |
742 | @end deffn | |
743 | ||
744 | For example: | |
745 | ||
746 | @example | |
747 | (define-syntax define-quotation-macros | |
748 | (lambda (x) | |
749 | (syntax-case x () | |
750 | ((_ (macro-name head-symbol) ...) | |
751 | #'(begin (define-syntax macro-name | |
752 | (lambda (x) | |
753 | (with-ellipsis ::: | |
754 | (syntax-case x () | |
755 | ((_ x :::) | |
756 | #'(quote (head-symbol x :::))))))) | |
757 | ...))))) | |
758 | (define-quotation-macros (quote-a a) (quote-b b) (quote-c c)) | |
759 | (quote-a 1 2 3) @result{} (a 1 2 3) | |
760 | @end example | |
761 | ||
762 | Note that @code{with-ellipsis} does not affect the ellipsis identifier | |
763 | of the generated code, unless @code{with-ellipsis} is included around | |
764 | the generated code. | |
765 | ||
9b0975f1 AW |
766 | @node Syntax Transformer Helpers |
767 | @subsection Syntax Transformer Helpers | |
768 | ||
769 | As noted in the previous section, Guile's syntax expander operates on | |
770 | syntax objects. Procedural macros consume and produce syntax objects. | |
771 | This section describes some of the auxiliary helpers that procedural | |
772 | macros can use to compare, generate, and query objects of this data | |
773 | type. | |
1fc8dcc7 AW |
774 | |
775 | @deffn {Scheme Procedure} bound-identifier=? a b | |
a4b4fbbd JE |
776 | Return @code{#t} if the syntax objects @var{a} and @var{b} refer to the |
777 | same lexically-bound identifier, or @code{#f} otherwise. | |
1fc8dcc7 AW |
778 | @end deffn |
779 | ||
780 | @deffn {Scheme Procedure} free-identifier=? a b | |
a4b4fbbd JE |
781 | Return @code{#t} if the syntax objects @var{a} and @var{b} refer to the |
782 | same free identifier, or @code{#f} otherwise. | |
1fc8dcc7 AW |
783 | @end deffn |
784 | ||
785 | @deffn {Scheme Procedure} generate-temporaries ls | |
786 | Return a list of temporary identifiers as long as @var{ls} is long. | |
787 | @end deffn | |
788 | ||
9b0975f1 AW |
789 | @deffn {Scheme Procedure} syntax-source x |
790 | Return the source properties that correspond to the syntax object | |
791 | @var{x}. @xref{Source Properties}, for more information. | |
792 | @end deffn | |
793 | ||
68fcf711 AW |
794 | Guile also offers some more experimental interfaces in a separate |
795 | module. As was the case with the Large Hadron Collider, it is unclear | |
796 | to our senior macrologists whether adding these interfaces will result | |
797 | in awesomeness or in the destruction of Guile via the creation of a | |
798 | singularity. We will preserve their functionality through the 2.0 | |
799 | series, but we reserve the right to modify them in a future stable | |
800 | series, to a more than usual degree. | |
801 | ||
802 | @example | |
803 | (use-modules (system syntax)) | |
804 | @end example | |
805 | ||
1ace4fbf AW |
806 | @deffn {Scheme Procedure} syntax-module id |
807 | Return the name of the module whose source contains the identifier | |
808 | @var{id}. | |
809 | @end deffn | |
810 | ||
8ae26afe | 811 | @deffn {Scheme Procedure} syntax-local-binding id [#:resolve-syntax-parameters?=#t] |
9b0975f1 AW |
812 | Resolve the identifer @var{id}, a syntax object, within the current |
813 | lexical environment, and return two values, the binding type and a | |
814 | binding value. The binding type is a symbol, which may be one of the | |
815 | following: | |
816 | ||
817 | @table @code | |
818 | @item lexical | |
819 | A lexically-bound variable. The value is a unique token (in the sense | |
820 | of @code{eq?}) identifying this binding. | |
821 | @item macro | |
822 | A syntax transformer, either local or global. The value is the | |
823 | transformer procedure. | |
8ae26afe AW |
824 | @item syntax-parameter |
825 | A syntax parameter (@pxref{Syntax Parameters}). By default, | |
826 | @code{syntax-local-binding} will resolve syntax parameters, so that this | |
827 | value will not be returned. Pass @code{#:resolve-syntax-parameters? #f} | |
828 | to indicate that you are interested in syntax parameters. The value is | |
829 | the default transformer procedure, as in @code{macro}. | |
9b0975f1 | 830 | @item pattern-variable |
1624e149 MW |
831 | A pattern variable, bound via @code{syntax-case}. The value is an |
832 | opaque object, internal to the expander. | |
833 | @item ellipsis | |
834 | An internal binding, bound via @code{with-ellipsis}. The value is the | |
835 | (anti-marked) local ellipsis identifier. | |
9b0975f1 AW |
836 | @item displaced-lexical |
837 | A lexical variable that has gone out of scope. This can happen if a | |
838 | badly-written procedural macro saves a syntax object, then attempts to | |
839 | introduce it in a context in which it is unbound. The value is | |
840 | @code{#f}. | |
841 | @item global | |
842 | A global binding. The value is a pair, whose head is the symbol, and | |
843 | whose tail is the name of the module in which to resolve the symbol. | |
844 | @item other | |
845 | Some other binding, like @code{lambda} or other core bindings. The | |
846 | value is @code{#f}. | |
847 | @end table | |
848 | ||
849 | This is a very low-level procedure, with limited uses. One case in | |
850 | which it is useful is to build abstractions that associate auxiliary | |
851 | information with macros: | |
852 | ||
853 | @example | |
854 | (define aux-property (make-object-property)) | |
855 | (define-syntax-rule (with-aux aux value) | |
856 | (let ((trans value)) | |
857 | (set! (aux-property trans) aux) | |
3d51e57c | 858 | trans)) |
9b0975f1 AW |
859 | (define-syntax retrieve-aux |
860 | (lambda (x) | |
861 | (syntax-case x () | |
862 | ((x id) | |
863 | (call-with-values (lambda () (syntax-local-binding #'id)) | |
864 | (lambda (type val) | |
865 | (with-syntax ((aux (datum->syntax #'here | |
866 | (and (eq? type 'macro) | |
867 | (aux-property val))))) | |
868 | #''aux))))))) | |
869 | (define-syntax foo | |
870 | (with-aux 'bar | |
871 | (syntax-rules () ((_) 'foo)))) | |
872 | (foo) | |
873 | @result{} foo | |
874 | (retrieve-aux foo) | |
875 | @result{} bar | |
876 | @end example | |
877 | ||
878 | @code{syntax-local-binding} must be called within the dynamic extent of | |
879 | a syntax transformer; to call it otherwise will signal an error. | |
880 | @end deffn | |
1fc8dcc7 | 881 | |
3d51e57c AW |
882 | @deffn {Scheme Procedure} syntax-locally-bound-identifiers id |
883 | Return a list of identifiers that were visible lexically when the | |
884 | identifier @var{id} was created, in order from outermost to innermost. | |
885 | ||
886 | This procedure is intended to be used in specialized procedural macros, | |
887 | to provide a macro with the set of bound identifiers that the macro can | |
888 | reference. | |
889 | ||
890 | As a technical implementation detail, the identifiers returned by | |
891 | @code{syntax-locally-bound-identifiers} will be anti-marked, like the | |
892 | syntax object that is given as input to a macro. This is to signal to | |
893 | the macro expander that these bindings were present in the original | |
894 | source, and do not need to be hygienically renamed, as would be the case | |
895 | with other introduced identifiers. See the discussion of hygiene in | |
896 | section 12.1 of the R6RS, for more information on marks. | |
897 | ||
898 | @example | |
899 | (define (local-lexicals id) | |
900 | (filter (lambda (x) | |
901 | (eq? (syntax-local-binding x) 'lexical)) | |
902 | (syntax-locally-bound-identifiers id))) | |
903 | (define-syntax lexicals | |
904 | (lambda (x) | |
905 | (syntax-case x () | |
906 | ((lexicals) #'(lexicals lexicals)) | |
907 | ((lexicals scope) | |
908 | (with-syntax (((id ...) (local-lexicals #'scope))) | |
909 | #'(list (cons 'id id) ...)))))) | |
910 | ||
911 | (let* ((x 10) (x 20)) (lexicals)) | |
912 | @result{} ((x . 10) (x . 20)) | |
913 | @end example | |
914 | @end deffn | |
915 | ||
916 | ||
e4955559 AW |
917 | @node Defmacros |
918 | @subsection Lisp-style Macro Definitions | |
919 | ||
1fc8dcc7 AW |
920 | The traditional way to define macros in Lisp is very similar to procedure |
921 | definitions. The key differences are that the macro definition body should | |
922 | return a list that describes the transformed expression, and that the definition | |
923 | is marked as a macro definition (rather than a procedure definition) by the use | |
924 | of a different definition keyword: in Lisp, @code{defmacro} rather than | |
925 | @code{defun}, and in Scheme, @code{define-macro} rather than @code{define}. | |
e4955559 AW |
926 | |
927 | @fnindex defmacro | |
928 | @fnindex define-macro | |
929 | Guile supports this style of macro definition using both @code{defmacro} | |
930 | and @code{define-macro}. The only difference between them is how the | |
931 | macro name and arguments are grouped together in the definition: | |
932 | ||
933 | @lisp | |
934 | (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{}) | |
935 | @end lisp | |
936 | ||
937 | @noindent | |
938 | is the same as | |
939 | ||
940 | @lisp | |
941 | (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{}) | |
942 | @end lisp | |
943 | ||
944 | @noindent | |
945 | The difference is analogous to the corresponding difference between | |
946 | Lisp's @code{defun} and Scheme's @code{define}. | |
947 | ||
1fc8dcc7 AW |
948 | Having read the previous section on @code{syntax-case}, it's probably clear that |
949 | Guile actually implements defmacros in terms of @code{syntax-case}, applying the | |
950 | transformer on the expression between invocations of @code{syntax->datum} and | |
951 | @code{datum->syntax}. This realization leads us to the problem with defmacros, | |
952 | that they do not preserve referential transparency. One can be careful to not | |
953 | introduce bindings into expanded code, via liberal use of @code{gensym}, but | |
954 | there is no getting around the lack of referential transparency for free | |
955 | bindings in the macro itself. | |
e4955559 | 956 | |
1fc8dcc7 | 957 | Even a macro as simple as our @code{when} from before is difficult to get right: |
e4955559 | 958 | |
1fc8dcc7 AW |
959 | @example |
960 | (define-macro (when cond exp . rest) | |
961 | `(if ,cond | |
962 | (begin ,exp . ,rest))) | |
e4955559 | 963 | |
1fc8dcc7 AW |
964 | (when #f (display "Launching missiles!\n")) |
965 | @result{} #f | |
e4955559 | 966 | |
1fc8dcc7 AW |
967 | (let ((if list)) |
968 | (when #f (display "Launching missiles!\n"))) | |
969 | @print{} Launching missiles! | |
970 | @result{} (#f #<unspecified>) | |
971 | @end example | |
972 | ||
973 | Guile's perspective is that defmacros have had a good run, but that modern | |
974 | macros should be written with @code{syntax-rules} or @code{syntax-case}. There | |
975 | are still many uses of defmacros within Guile itself, but we will be phasing | |
976 | them out over time. Of course we won't take away @code{defmacro} or | |
977 | @code{define-macro} themselves, as there is lots of code out there that uses | |
978 | them. | |
e4955559 AW |
979 | |
980 | ||
981 | @node Identifier Macros | |
982 | @subsection Identifier Macros | |
983 | ||
6ffd4131 AW |
984 | When the syntax expander sees a form in which the first element is a macro, the |
985 | whole form gets passed to the macro's syntax transformer. One may visualize this | |
986 | as: | |
987 | ||
988 | @example | |
989 | (define-syntax foo foo-transformer) | |
990 | (foo @var{arg}...) | |
991 | ;; expands via | |
992 | (foo-transformer #'(foo @var{arg}...)) | |
993 | @end example | |
994 | ||
995 | If, on the other hand, a macro is referenced in some other part of a form, the | |
996 | syntax transformer is invoked with only the macro reference, not the whole form. | |
997 | ||
998 | @example | |
999 | (define-syntax foo foo-transformer) | |
1000 | foo | |
1001 | ;; expands via | |
1002 | (foo-transformer #'foo) | |
1003 | @end example | |
1004 | ||
1005 | This allows bare identifier references to be replaced programmatically via a | |
1006 | macro. @code{syntax-rules} provides some syntax to effect this transformation | |
1007 | more easily. | |
1008 | ||
1009 | @deffn {Syntax} identifier-syntax exp | |
ecb87335 | 1010 | Returns a macro transformer that will replace occurrences of the macro with |
6ffd4131 AW |
1011 | @var{exp}. |
1012 | @end deffn | |
1013 | ||
1014 | For example, if you are importing external code written in terms of @code{fx+}, | |
1015 | the fixnum addition operator, but Guile doesn't have @code{fx+}, you may use the | |
1016 | following to replace @code{fx+} with @code{+}: | |
1017 | ||
1018 | @example | |
1019 | (define-syntax fx+ (identifier-syntax +)) | |
1020 | @end example | |
1021 | ||
69724dde AW |
1022 | There is also special support for recognizing identifiers on the |
1023 | left-hand side of a @code{set!} expression, as in the following: | |
1024 | ||
1025 | @example | |
1026 | (define-syntax foo foo-transformer) | |
1027 | (set! foo @var{val}) | |
1028 | ;; expands via | |
1029 | (foo-transformer #'(set! foo @var{val})) | |
a4b4fbbd | 1030 | ;; if foo-transformer is a "variable transformer" |
69724dde AW |
1031 | @end example |
1032 | ||
1033 | As the example notes, the transformer procedure must be explicitly | |
1034 | marked as being a ``variable transformer'', as most macros aren't | |
7545ddd4 | 1035 | written to discriminate on the form in the operator position. |
69724dde AW |
1036 | |
1037 | @deffn {Scheme Procedure} make-variable-transformer transformer | |
1038 | Mark the @var{transformer} procedure as being a ``variable | |
1039 | transformer''. In practice this means that, when bound to a syntactic | |
1040 | keyword, it may detect references to that keyword on the left-hand-side | |
1041 | of a @code{set!}. | |
1042 | ||
1043 | @example | |
1044 | (define bar 10) | |
1045 | (define-syntax bar-alias | |
1046 | (make-variable-transformer | |
1047 | (lambda (x) | |
1048 | (syntax-case x (set!) | |
1049 | ((set! var val) #'(set! bar val)) | |
1050 | ((var arg ...) #'(bar arg ...)) | |
1051 | (var (identifier? #'var) #'bar))))) | |
1052 | ||
1053 | bar-alias @result{} 10 | |
1054 | (set! bar-alias 20) | |
1055 | bar @result{} 20 | |
1056 | (set! bar 30) | |
1057 | bar-alias @result{} 30 | |
1058 | @end example | |
1059 | @end deffn | |
1060 | ||
ecb87335 | 1061 | There is an extension to identifier-syntax which allows it to handle the |
69724dde AW |
1062 | @code{set!} case as well: |
1063 | ||
1064 | @deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2) | |
1065 | Create a variable transformer. The first clause is used for references | |
1066 | to the variable in operator or operand position, and the second for | |
1067 | appearances of the variable on the left-hand-side of an assignment. | |
1068 | ||
1069 | For example, the previous @code{bar-alias} example could be expressed | |
1070 | more succinctly like this: | |
1071 | ||
1072 | @example | |
1073 | (define-syntax bar-alias | |
1074 | (identifier-syntax | |
1075 | (var bar) | |
1076 | ((set! var val) (set! bar val)))) | |
1077 | @end example | |
1078 | ||
1079 | @noindent | |
1080 | As before, the templates in @code{identifier-syntax} forms do not need | |
1081 | wrapping in @code{#'} syntax forms. | |
1082 | @end deffn | |
1083 | ||
6ffd4131 | 1084 | |
729b62bd IP |
1085 | @node Syntax Parameters |
1086 | @subsection Syntax Parameters | |
1087 | ||
866ecf54 AW |
1088 | Syntax parameters@footnote{Described in the paper @cite{Keeping it Clean |
1089 | with Syntax Parameters} by Barzilay, Culpepper and Flatt.} are a | |
1090 | mechanism for rebinding a macro definition within the dynamic extent of | |
1091 | a macro expansion. This provides a convenient solution to one of the | |
1092 | most common types of unhygienic macro: those that introduce a unhygienic | |
1093 | binding each time the macro is used. Examples include a @code{lambda} | |
1094 | form with a @code{return} keyword, or class macros that introduce a | |
1095 | special @code{self} binding. | |
729b62bd IP |
1096 | |
1097 | With syntax parameters, instead of introducing the binding | |
866ecf54 AW |
1098 | unhygienically each time, we instead create one binding for the keyword, |
1099 | which we can then adjust later when we want the keyword to have a | |
1100 | different meaning. As no new bindings are introduced, hygiene is | |
1101 | preserved. This is similar to the dynamic binding mechanisms we have at | |
1102 | run-time (@pxref{SRFI-39, parameters}), except that the dynamic binding | |
1103 | only occurs during macro expansion. The code after macro expansion | |
1104 | remains lexically scoped. | |
729b62bd IP |
1105 | |
1106 | @deffn {Syntax} define-syntax-parameter keyword transformer | |
866ecf54 AW |
1107 | Binds @var{keyword} to the value obtained by evaluating |
1108 | @var{transformer}. The @var{transformer} provides the default expansion | |
1109 | for the syntax parameter, and in the absence of | |
1110 | @code{syntax-parameterize}, is functionally equivalent to | |
1111 | @code{define-syntax}. Usually, you will just want to have the | |
1112 | @var{transformer} throw a syntax error indicating that the @var{keyword} | |
1113 | is supposed to be used in conjunction with another macro, for example: | |
729b62bd IP |
1114 | @example |
1115 | (define-syntax-parameter return | |
1116 | (lambda (stx) | |
1117 | (syntax-violation 'return "return used outside of a lambda^" stx))) | |
1118 | @end example | |
1119 | @end deffn | |
1120 | ||
1121 | @deffn {Syntax} syntax-parameterize ((keyword transformer) @dots{}) exp @dots{} | |
1122 | Adjusts @var{keyword} @dots{} to use the values obtained by evaluating | |
866ecf54 AW |
1123 | their @var{transformer} @dots{}, in the expansion of the @var{exp} |
1124 | @dots{} forms. Each @var{keyword} must be bound to a syntax-parameter. | |
1125 | @code{syntax-parameterize} differs from @code{let-syntax}, in that the | |
1126 | binding is not shadowed, but adjusted, and so uses of the keyword in the | |
1127 | expansion of @var{exp} @dots{} use the new transformers. This is | |
1128 | somewhat similar to how @code{parameterize} adjusts the values of | |
1129 | regular parameters, rather than creating new bindings. | |
729b62bd IP |
1130 | |
1131 | @example | |
1132 | (define-syntax lambda^ | |
1133 | (syntax-rules () | |
866ecf54 | 1134 | [(lambda^ argument-list body body* ...) |
729b62bd IP |
1135 | (lambda argument-list |
1136 | (call-with-current-continuation | |
1137 | (lambda (escape) | |
866ecf54 AW |
1138 | ;; In the body we adjust the 'return' keyword so that calls |
1139 | ;; to 'return' are replaced with calls to the escape | |
1140 | ;; continuation. | |
729b62bd IP |
1141 | (syntax-parameterize ([return (syntax-rules () |
1142 | [(return vals (... ...)) | |
1143 | (escape vals (... ...))])]) | |
866ecf54 | 1144 | body body* ...))))])) |
729b62bd | 1145 | |
866ecf54 | 1146 | ;; Now we can write functions that return early. Here, 'product' will |
729b62bd IP |
1147 | ;; return immediately if it sees any 0 element. |
1148 | (define product | |
1149 | (lambda^ (list) | |
1150 | (fold (lambda (n o) | |
1151 | (if (zero? n) | |
1152 | (return 0) | |
1153 | (* n o))) | |
1154 | 1 | |
1155 | list))) | |
1156 | @end example | |
1157 | @end deffn | |
1158 | ||
1159 | ||
e4955559 AW |
1160 | @node Eval When |
1161 | @subsection Eval-when | |
1162 | ||
6ffd4131 AW |
1163 | As @code{syntax-case} macros have the whole power of Scheme available to them, |
1164 | they present a problem regarding time: when a macro runs, what parts of the | |
1165 | program are available for the macro to use? | |
e4955559 | 1166 | |
6ffd4131 AW |
1167 | The default answer to this question is that when you import a module (via |
1168 | @code{define-module} or @code{use-modules}), that module will be loaded up at | |
1169 | expansion-time, as well as at run-time. Additionally, top-level syntactic | |
1170 | definitions within one compilation unit made by @code{define-syntax} are also | |
1171 | evaluated at expansion time, in the order that they appear in the compilation | |
1172 | unit (file). | |
1173 | ||
1174 | But if a syntactic definition needs to call out to a normal procedure at | |
1175 | expansion-time, it might well need need special declarations to indicate that | |
1176 | the procedure should be made available at expansion-time. | |
1177 | ||
1178 | For example, the following code will work at a REPL, but not in a file: | |
1179 | ||
1180 | @example | |
1181 | ;; incorrect | |
1182 | (use-modules (srfi srfi-19)) | |
1183 | (define (date) (date->string (current-date))) | |
1184 | (define-syntax %date (identifier-syntax (date))) | |
1185 | (define *compilation-date* %date) | |
1186 | @end example | |
e4955559 | 1187 | |
6ffd4131 AW |
1188 | It works at a REPL because the expressions are evaluated one-by-one, in order, |
1189 | but if placed in a file, the expressions are expanded one-by-one, but not | |
1190 | evaluated until the compiled file is loaded. | |
1191 | ||
1192 | The fix is to use @code{eval-when}. | |
1193 | ||
1194 | @example | |
1195 | ;; correct: using eval-when | |
1196 | (use-modules (srfi srfi-19)) | |
fc1cb3fa | 1197 | (eval-when (expand load eval) |
6ffd4131 AW |
1198 | (define (date) (date->string (current-date)))) |
1199 | (define-syntax %date (identifier-syntax (date))) | |
1200 | (define *compilation-date* %date) | |
1201 | @end example | |
1202 | ||
1203 | @deffn {Syntax} eval-when conditions exp... | |
fc1cb3fa MW |
1204 | Evaluate @var{exp...} under the given @var{conditions}. Valid |
1205 | conditions include: | |
1206 | ||
1207 | @table @code | |
1208 | @item expand | |
1209 | Evaluate during macro expansion, whether compiling or not. | |
1210 | ||
1211 | @item load | |
1212 | Evaluate during the evaluation phase of compiled code, e.g. when loading | |
1213 | a compiled module or running compiled code at the REPL. | |
1214 | ||
1215 | @item eval | |
1216 | Evaluate during the evaluation phase of non-compiled code. | |
1217 | ||
1218 | @item compile | |
1219 | Evaluate during macro expansion, but only when compiling. | |
1220 | @end table | |
1221 | ||
1222 | In other words, when using the primitive evaluator, @code{eval-when} | |
1223 | expressions with @code{expand} are run during macro expansion, and those | |
1224 | with @code{eval} are run during the evaluation phase. | |
1225 | ||
1226 | When using the compiler, @code{eval-when} expressions with either | |
1227 | @code{expand} or @code{compile} are run during macro expansion, and | |
1228 | those with @code{load} are run during the evaluation phase. | |
1229 | ||
1230 | When in doubt, use the three conditions @code{(expand load eval)}, as in | |
1231 | the example above. Other uses of @code{eval-when} may void your | |
1232 | warranty or poison your cat. | |
6ffd4131 AW |
1233 | @end deffn |
1234 | ||
67915ab0 AW |
1235 | @node Macro Expansion |
1236 | @subsection Macro Expansion | |
1237 | ||
1238 | Usually, macros are expanded on behalf of the user as needed. Macro | |
1239 | expansion is an integral part of @code{eval} and @code{compile}. Users | |
1240 | can also expand macros at the REPL prompt via the @code{expand} REPL | |
1241 | command; @xref{Compile Commands}. | |
1242 | ||
1243 | Macros can also be expanded programmatically, via @code{macroexpand}, | |
1244 | but the details get a bit hairy for two reasons. | |
1245 | ||
1246 | The first complication is that the result of macro-expansion isn't | |
1247 | Scheme: it's Tree-IL, Guile's high-level intermediate language. | |
1248 | @xref{Tree-IL}. As ``hygienic macros'' can produce identifiers that are | |
1249 | distinct but have the same name, the output format needs to be able to | |
1250 | represent distinctions between variable identities and names. Again, | |
660f2775 AW |
1251 | @xref{Tree-IL}, for all the details. The easiest thing is to just run |
1252 | @code{tree-il->scheme} on the result of macro-expansion: | |
67915ab0 AW |
1253 | |
1254 | @lisp | |
1255 | (macroexpand '(+ 1 2)) | |
1256 | @result{} | |
1257 | #<tree-il (call (toplevel +) (const 1) (const 2))> | |
1258 | ||
1259 | (use-modules (language tree-il)) | |
1260 | (tree-il->scheme (macroexpand '(+ 1 2))) | |
1261 | @result{} | |
1262 | (+ 1 2) | |
1263 | @end lisp | |
1264 | ||
1265 | The second complication involves @code{eval-when}. As an example, what | |
1266 | would it mean to macro-expand the definition of a macro? | |
1267 | ||
1268 | @lisp | |
1269 | (macroexpand '(define-syntax qux (identifier-syntax 'bar))) | |
1270 | @result{} | |
1271 | ? | |
1272 | @end lisp | |
1273 | ||
1274 | The answer is that it depends who is macro-expanding, and why. Do you | |
1275 | define the macro in the current environment? Residualize a macro | |
1276 | definition? Both? Neither? The default is to expand in ``eval'' mode, | |
1277 | which means an @code{eval-when} clauses will only proceed when | |
1278 | @code{eval} (or @code{expand}) is in its condition set. Top-level | |
1279 | macros will be @code{eval}'d in the top-level environment. | |
1280 | ||
1281 | In this way @code{(macroexpand @var{foo})} is equivalent to | |
1282 | @code{(macroexpand @var{foo} 'e '(eval))}. The second argument is the | |
1283 | mode (@code{'e} for ``eval'') and the second is the | |
1284 | eval-syntax-expanders-when parameter (only @code{eval} in this default | |
1285 | setting). | |
1286 | ||
1287 | But if you are compiling the macro definition, probably you want to | |
1288 | reify the macro definition itself. In that case you pass @code{'c} as | |
1289 | the second argument to @code{macroexpand}. But probably you want the | |
1290 | macro definition to be present at compile time as well, so you pass | |
1291 | @code{'(compile load eval)} as the @var{esew} parameter. In fact | |
1292 | @code{(compile @var{foo} #:to 'tree-il)} is entirely equivalent to | |
1293 | @code{(macroexpand @var{foo} 'c '(compile load eval))}; @xref{The Scheme | |
1294 | Compiler}. | |
1295 | ||
1296 | It's a terrible interface; we know. The macroexpander is somewhat | |
1297 | tricksy regarding modes, so unless you are building a macro-expanding | |
1298 | tool, we suggest to avoid invoking it directly. | |
1299 | ||
1300 | ||
03dfed84 AW |
1301 | @node Hygiene and the Top-Level |
1302 | @subsection Hygiene and the Top-Level | |
1303 | ||
1304 | Consider the following macro. | |
1305 | ||
1306 | @lisp | |
1307 | (define-syntax-rule (defconst name val) | |
1308 | (begin | |
1309 | (define t val) | |
1310 | (define-syntax-rule (name) t))) | |
1311 | @end lisp | |
1312 | ||
1313 | If we use it to make a couple of bindings: | |
1314 | ||
1315 | @lisp | |
1316 | (defconst foo 42) | |
1317 | (defconst bar 37) | |
1318 | @end lisp | |
1319 | ||
1320 | The expansion would look something like this: | |
1321 | ||
1322 | @lisp | |
1323 | (begin | |
1324 | (define t 42) | |
1325 | (define-syntax-rule (foo) t)) | |
1326 | (begin | |
1327 | (define t 37) | |
1328 | (define-syntax-rule (bar) t)) | |
1329 | @end lisp | |
1330 | ||
1331 | As the two @code{t} bindings were introduced by the macro, they should | |
1332 | be introduced hygienically -- and indeed they are, inside a lexical | |
1333 | contour (a @code{let} or some other lexical scope). The @code{t} | |
1334 | reference in @code{foo} is distinct to the reference in @code{bar}. | |
1335 | ||
1336 | At the top-level things are more complicated. Before Guile 2.2, a use | |
1337 | of @code{defconst} at the top-level would not introduce a fresh binding | |
1338 | for @code{t}. This was consistent with a weaselly interpretation of the | |
1339 | Scheme standard, in which all possible bindings may be assumed to exist, | |
1340 | at the top-level, and in which we merely take advantage of toplevel | |
1341 | @code{define} of an existing binding being equivalent to @code{set!}. | |
1342 | But it's not a good reason. | |
1343 | ||
1344 | The solution is to create fresh names for all bindings introduced by | |
1345 | macros -- not just bindings in lexical contours, but also bindings | |
1346 | introduced at the top-level. | |
1347 | ||
1348 | However, the obvious strategy of just giving random names to introduced | |
1349 | toplevel identifiers poses a problem for separate compilation. Consider | |
1350 | without loss of generality a @code{defconst} of @code{foo} in module | |
1351 | @code{a} that introduces the fresh top-level name @code{t-1}. If we | |
1352 | then compile a module @code{b} that uses @code{foo}, there is now a | |
1353 | reference to @code{t-1} in module @code{b}. If module @code{a} is then | |
1354 | expanded again, for whatever reason, for example in a simple | |
1355 | recompilation, the introduced @code{t} gets a fresh name; say, | |
1356 | @code{t-2}. Now module @code{b} has broken because module @code{a} no | |
1357 | longer has a binding for @code{t-1}. | |
1358 | ||
1359 | If introduced top-level identifiers ``escape'' a module, in whatever | |
1360 | way, they then form part of the binary interface (ABI) of a module. It | |
1361 | is unacceptable from an engineering point of view to allow the ABI to | |
1362 | change randomly. (It also poses practical problems in meeting the | |
1363 | recompilation conditions of the Lesser GPL license, for such modules.) | |
1364 | For this reason many people prefer to never use identifier-introducing | |
1365 | macros at the top-level, instead making those macros receive the names | |
1366 | for their introduced identifiers as part of their arguments, or to | |
1367 | construct them programmatically and use @code{datum->syntax}. But this | |
1368 | approach requires omniscience as to the implementation of all macros one | |
1369 | might use, and also limits the expressive power of Scheme macros. | |
1370 | ||
1371 | There is no perfect solution to this issue. Guile does a terrible thing | |
1372 | here. When it goes to introduce a top-level identifier, Guile gives the | |
1373 | identifier a pseudo-fresh name: a name that depends on the hash of the | |
1374 | source expression in which the name occurs. The result in this case is | |
1375 | that the introduced definitions expand as: | |
1376 | ||
1377 | @lisp | |
1378 | (begin | |
1379 | (define t-1dc5e42de7c1050c 42) | |
1380 | (define-syntax-rule (foo) t-1dc5e42de7c1050c)) | |
1381 | (begin | |
1382 | (define t-10cb8ce9fdddd6e9 37) | |
1383 | (define-syntax-rule (bar) t-10cb8ce9fdddd6e9)) | |
1384 | @end lisp | |
1385 | ||
1386 | However, note that as the hash depends solely on the expression | |
1387 | introducing the definition, we also have: | |
1388 | ||
1389 | @lisp | |
1390 | (defconst baz 42) | |
1391 | @result{} (begin | |
1392 | (define t-1dc5e42de7c1050c 42) | |
1393 | (define-syntax-rule (baz) t-1dc5e42de7c1050c)) | |
1394 | @end lisp | |
1395 | ||
1396 | Note that the introduced binding has the same name! This is because the | |
1397 | source expression, @code{(define t 42)}, was the same. Probably you | |
1398 | will never see an error in this area, but it is important to understand | |
1399 | the components of the interface of a module, and that interface may | |
1400 | include macro-introduced identifiers. | |
1401 | ||
1402 | ||
6ffd4131 AW |
1403 | @node Internal Macros |
1404 | @subsection Internal Macros | |
e4955559 AW |
1405 | |
1406 | @deffn {Scheme Procedure} make-syntax-transformer name type binding | |
6ffd4131 AW |
1407 | Construct a syntax transformer object. This is part of Guile's low-level support |
1408 | for syntax-case. | |
e4955559 AW |
1409 | @end deffn |
1410 | ||
1411 | @deffn {Scheme Procedure} macro? obj | |
1412 | @deffnx {C Function} scm_macro_p (obj) | |
a4b4fbbd JE |
1413 | Return @code{#t} if @var{obj} is a syntax transformer, or @code{#f} |
1414 | otherwise. | |
6ffd4131 AW |
1415 | |
1416 | Note that it's a bit difficult to actually get a macro as a first-class object; | |
1417 | simply naming it (like @code{case}) will produce a syntax error. But it is | |
1418 | possible to get these objects using @code{module-ref}: | |
1419 | ||
1420 | @example | |
1421 | (macro? (module-ref (current-module) 'case)) | |
1422 | @result{} #t | |
1423 | @end example | |
e4955559 AW |
1424 | @end deffn |
1425 | ||
1426 | @deffn {Scheme Procedure} macro-type m | |
1427 | @deffnx {C Function} scm_macro_type (m) | |
6ffd4131 AW |
1428 | Return the @var{type} that was given when @var{m} was constructed, via |
1429 | @code{make-syntax-transformer}. | |
e4955559 AW |
1430 | @end deffn |
1431 | ||
1432 | @deffn {Scheme Procedure} macro-name m | |
1433 | @deffnx {C Function} scm_macro_name (m) | |
1434 | Return the name of the macro @var{m}. | |
1435 | @end deffn | |
1436 | ||
e4955559 AW |
1437 | @deffn {Scheme Procedure} macro-binding m |
1438 | @deffnx {C Function} scm_macro_binding (m) | |
1439 | Return the binding of the macro @var{m}. | |
1440 | @end deffn | |
1441 | ||
6ffd4131 AW |
1442 | @deffn {Scheme Procedure} macro-transformer m |
1443 | @deffnx {C Function} scm_macro_transformer (m) | |
1444 | Return the transformer of the macro @var{m}. This will return a procedure, for | |
1445 | which one may ask the docstring. That's the whole reason this section is | |
1446 | documented. Actually a part of the result of @code{macro-binding}. | |
1447 | @end deffn | |
1448 | ||
e4955559 AW |
1449 | |
1450 | @c Local Variables: | |
1451 | @c TeX-master: "guile.texi" | |
1452 | @c End: |