2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2011, 2012
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
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}.
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:
23 (@var{macro-name} @var{macro-args} @dots{})
26 @cindex macro expansion
27 @cindex domain-specific language
28 @cindex embedded domain-specific language
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
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.}.
38 * Defining Macros:: Binding macros, globally and locally.
39 * Syntax Rules:: Pattern-driven macros.
40 * Syntax Case:: Procedural, hygienic macros.
41 * Syntax Transformer Helpers:: Helpers for use in procedural macros.
42 * Defmacros:: Lisp-style macros.
43 * Identifier Macros:: Identifier macros.
44 * Syntax Parameters:: Syntax Parameters.
45 * Eval When:: Affecting the expand-time environment.
46 * Internal Macros:: Macros as first-class values.
50 @subsection Defining Macros
52 A macro is a binding between a keyword and a syntax transformer. Since it's
53 difficult to discuss @code{define-syntax} without discussing the format of
54 transformers, consider the following example macro definition:
59 ((when condition exp ...)
65 (display "let's go\n"))
70 In this example, the @code{when} binding is bound with @code{define-syntax}.
71 Syntax transformers are discussed in more depth in @ref{Syntax Rules} and
74 @deffn {Syntax} define-syntax keyword transformer
75 Bind @var{keyword} to the syntax transformer obtained by evaluating
78 After a macro has been defined, further instances of @var{keyword} in Scheme
79 source code will invoke the syntax transformer defined by @var{transformer}.
82 One can also establish local syntactic bindings with @code{let-syntax}.
84 @deffn {Syntax} let-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{}
85 Bind each @var{keyword} to its corresponding @var{transformer} while
86 expanding @var{exp1} @var{exp2} @enddots{}.
88 A @code{let-syntax} binding only exists at expansion-time.
93 ((unless condition exp ...)
99 @result{} "rock rock rock"
103 A @code{define-syntax} form is valid anywhere a definition may appear: at the
104 top-level, or locally. Just as a local @code{define} expands out to an instance
105 of @code{letrec}, a local @code{define-syntax} expands out to
106 @code{letrec-syntax}.
108 @deffn {Syntax} letrec-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{}
109 Bind each @var{keyword} to its corresponding @var{transformer} while
110 expanding @var{exp1} @var{exp2} @enddots{}.
112 In the spirit of @code{letrec} versus @code{let}, an expansion produced by
113 @var{transformer} may reference a @var{keyword} bound by the
114 same @var{letrec-syntax}.
117 (letrec-syntax ((my-or
123 ((my-or exp rest ...)
127 (my-or rest ...)))))))
128 (my-or #f "rockaway beach"))
129 @result{} "rockaway beach"
134 @subsection Syntax-rules Macros
136 @code{syntax-rules} macros are simple, pattern-driven syntax transformers, with
137 a beauty worthy of Scheme.
139 @deffn {Syntax} syntax-rules literals (pattern template)...
140 Create a syntax transformer that will rewrite an expression using the rules
141 embodied in the @var{pattern} and @var{template} clauses.
144 A @code{syntax-rules} macro consists of three parts: the literals (if any), the
145 patterns, and as many templates as there are patterns.
147 When the syntax expander sees the invocation of a @code{syntax-rules} macro, it
148 matches the expression against the patterns, in order, and rewrites the
149 expression using the template from the first matching pattern. If no pattern
150 matches, a syntax error is signalled.
152 @subsubsection Patterns
154 We have already seen some examples of patterns in the previous section:
155 @code{(unless condition exp ...)}, @code{(my-or exp)}, and so on. A pattern is
156 structured like the expression that it is to match. It can have nested structure
157 as well, like @code{(let ((var val) ...) exp exp* ...)}. Broadly speaking,
158 patterns are made of lists, improper lists, vectors, identifiers, and datums.
159 Users can match a sequence of patterns using the ellipsis (@code{...}).
161 Identifiers in a pattern are called @dfn{literals} if they are present in the
162 @code{syntax-rules} literals list, and @dfn{pattern variables} otherwise. When
163 building up the macro output, the expander replaces instances of a pattern
164 variable in the template with the matched subexpression.
172 @result{} (foo . bar)
175 An improper list of patterns matches as rest arguments do:
180 ((_ (var val) . exps)
181 (let ((var val)) . exps))))
184 However this definition of @code{let1} probably isn't what you want, as the tail
185 pattern @var{exps} will match non-lists, like @code{(let1 (foo 'bar) . baz)}. So
186 often instead of using improper lists as patterns, ellipsized patterns are
187 better. Instances of a pattern variable in the template must be followed by an
193 ((_ (var val) exp ...)
194 (let ((var val)) exp ...))))
197 This @code{let1} probably still doesn't do what we want, because the body
198 matches sequences of zero expressions, like @code{(let1 (foo 'bar))}. In this
199 case we need to assert we have at least one body expression. A common idiom for
200 this is to name the ellipsized pattern variable with an asterisk:
205 ((_ (var val) exp exp* ...)
206 (let ((var val)) exp exp* ...))))
209 A vector of patterns matches a vector whose contents match the patterns,
210 including ellipsizing and tail patterns.
215 ((_ #((var val) ...) exp exp* ...)
216 (let ((var val) ...) exp exp* ...))))
217 (letv #((foo 'bar)) foo)
221 Literals are used to match specific datums in an expression, like the use of
222 @code{=>} and @code{else} in @code{cond} expressions.
226 (syntax-rules (=> else)
229 (if exp (fun exp) #f)))
230 ((cond1 test exp exp* ...)
231 (if test (begin exp exp* ...)))
232 ((cond1 else exp exp* ...)
233 (begin exp exp* ...))))
235 (define (square x) (* x x))
239 (cond1 10 => square))
240 @result{} #<procedure square (x)>
243 A literal matches an input expression if the input expression is an identifier
244 with the same name as the literal, and both are unbound@footnote{Language
245 lawyers probably see the need here for use of @code{literal-identifier=?} rather
246 than @code{free-identifier=?}, and would probably be correct. Patches
249 If a pattern is not a list, vector, or an identifier, it matches as a literal,
253 (define-syntax define-matcher-macro
261 (define-matcher-macro is-literal-foo? "foo")
263 (is-literal-foo? "foo")
265 (is-literal-foo? "bar")
268 (is-literal-foo? foo))
272 The last example indicates that matching happens at expansion-time, not
275 Syntax-rules macros are always used as @code{(@var{macro} . @var{args})}, and
276 the @var{macro} will always be a symbol. Correspondingly, a @code{syntax-rules}
277 pattern must be a list (proper or improper), and the first pattern in that list
278 must be an identifier. Incidentally it can be any identifier -- it doesn't have
279 to actually be the name of the macro. Thus the following three are equivalent:
285 (if c (begin e ...)))))
290 (if c (begin e ...)))))
294 ((something-else-entirely c e ...)
295 (if c (begin e ...)))))
298 For clarity, use one of the first two variants. Also note that since the pattern
299 variable will always match the macro itself (e.g., @code{cond1}), it is actually
300 left unbound in the template.
302 @subsubsection Hygiene
304 @code{syntax-rules} macros have a magical property: they preserve referential
305 transparency. When you read a macro definition, any free bindings in that macro
306 are resolved relative to the macro definition; and when you read a macro
307 instantiation, all free bindings in that expression are resolved relative to the
310 This property is sometimes known as @dfn{hygiene}, and it does aid in code
311 cleanliness. In your macro definitions, you can feel free to introduce temporary
312 variables, without worrying about inadvertently introducing bindings into the
315 Consider the definition of @code{my-or} from the previous section:
324 ((my-or exp rest ...)
328 (my-or rest ...))))))
331 A naive expansion of @code{(let ((t #t)) (my-or #f t))} would yield:
341 Which clearly is not what we want. Somehow the @code{t} in the definition is
342 distinct from the @code{t} at the site of use; and it is indeed this distinction
343 that is maintained by the syntax expander, when expanding hygienic macros.
345 This discussion is mostly relevant in the context of traditional Lisp macros
346 (@pxref{Defmacros}), which do not preserve referential transparency. Hygiene
347 adds to the expressive power of Scheme.
349 @subsubsection Shorthands
351 One often ends up writing simple one-clause @code{syntax-rules} macros.
352 There is a convenient shorthand for this idiom, in the form of
353 @code{define-syntax-rule}.
355 @deffn {Syntax} define-syntax-rule (keyword . pattern) [docstring] template
356 Define @var{keyword} as a new @code{syntax-rules} macro with one clause.
359 Cast into this form, our @code{when} example is significantly shorter:
362 (define-syntax-rule (when c e ...)
363 (if c (begin e ...)))
366 @subsubsection Further Information
368 For a formal definition of @code{syntax-rules} and its pattern language, see
369 @xref{Macros, , Macros, r5rs, Revised(5) Report on the Algorithmic Language
372 @code{syntax-rules} macros are simple and clean, but do they have limitations.
373 They do not lend themselves to expressive error messages: patterns either match
374 or they don't. Their ability to generate code is limited to template-driven
375 expansion; often one needs to define a number of helper macros to get real work
376 done. Sometimes one wants to introduce a binding into the lexical context of the
377 generated code; this is impossible with @code{syntax-rules}. Relatedly, they
378 cannot programmatically generate identifiers.
380 The solution to all of these problems is to use @code{syntax-case} if you need
381 its features. But if for some reason you're stuck with @code{syntax-rules}, you
382 might enjoy Joe Marshall's
383 @uref{http://sites.google.com/site/evalapply/eccentric.txt,@code{syntax-rules}
384 Primer for the Merely Eccentric}.
387 @subsection Support for the @code{syntax-case} System
389 @code{syntax-case} macros are procedural syntax transformers, with a power
392 @deffn {Syntax} syntax-case syntax literals (pattern [guard] exp)...
393 Match the syntax object @var{syntax} against the given patterns, in order. If a
394 @var{pattern} matches, return the result of evaluating the associated @var{exp}.
397 Compare the following definitions of @code{when}:
403 (if test (begin e e* ...)))))
409 #'(if test (begin e e* ...))))))
412 Clearly, the @code{syntax-case} definition is similar to its @code{syntax-rules}
413 counterpart, and equally clearly there are some differences. The
414 @code{syntax-case} definition is wrapped in a @code{lambda}, a function of one
415 argument; that argument is passed to the @code{syntax-case} invocation; and the
416 ``return value'' of the macro has a @code{#'} prefix.
418 All of these differences stem from the fact that @code{syntax-case} does not
419 define a syntax transformer itself -- instead, @code{syntax-case} expressions
420 provide a way to destructure a @dfn{syntax object}, and to rebuild syntax
423 So the @code{lambda} wrapper is simply a leaky implementation detail, that
424 syntax transformers are just functions that transform syntax to syntax. This
425 should not be surprising, given that we have already described macros as
426 ``programs that write programs''. @code{syntax-case} is simply a way to take
427 apart and put together program text, and to be a valid syntax transformer it
428 needs to be wrapped in a procedure.
430 Unlike traditional Lisp macros (@pxref{Defmacros}), @code{syntax-case} macros
431 transform syntax objects, not raw Scheme forms. Recall the naive expansion of
432 @code{my-or} given in the previous section:
443 Raw Scheme forms simply don't have enough information to distinguish the first
444 two @code{t} instances in @code{(if t t t)} from the third @code{t}. So instead
445 of representing identifiers as symbols, the syntax expander represents
446 identifiers as annotated syntax objects, attaching such information to those
447 syntax objects as is needed to maintain referential transparency.
449 @deffn {Syntax} syntax form
450 Create a syntax object wrapping @var{form} within the current lexical context.
453 Syntax objects are typically created internally to the process of expansion, but
454 it is possible to create them outside of syntax expansion:
457 (syntax (foo bar baz))
458 @result{} #<some representation of that syntax>
462 However it is more common, and useful, to create syntax objects when building
463 output from a @code{syntax-case} expression.
470 (syntax (+ exp 1))))))
473 It is not strictly necessary for a @code{syntax-case} expression to return a
474 syntax object, because @code{syntax-case} expressions can be used in helper
475 functions, or otherwise used outside of syntax expansion itself. However a
476 syntax transformer procedure must return a syntax object, so most uses of
477 @code{syntax-case} do end up returning syntax objects.
479 Here in this case, the form that built the return value was @code{(syntax (+ exp
480 1))}. The interesting thing about this is that within a @code{syntax}
481 expression, any appearance of a pattern variable is substituted into the
482 resulting syntax object, carrying with it all relevant metadata from the source
483 expression, such as lexical identity and source location.
485 Indeed, a pattern variable may only be referenced from inside a @code{syntax}
486 form. The syntax expander would raise an error when defining @code{add1} if it
487 found @var{exp} referenced outside a @code{syntax} form.
489 Since @code{syntax} appears frequently in macro-heavy code, it has a special
490 reader macro: @code{#'}. @code{#'foo} is transformed by the reader into
491 @code{(syntax foo)}, just as @code{'foo} is transformed into @code{(quote foo)}.
493 The pattern language used by @code{syntax-case} is conveniently the same
494 language used by @code{syntax-rules}. Given this, Guile actually defines
495 @code{syntax-rules} in terms of @code{syntax-case}:
498 (define-syntax syntax-rules
501 ((_ (k ...) ((keyword . pattern) template) ...)
503 (syntax-case x (k ...)
504 ((dummy . pattern) #'template)
510 @subsubsection Why @code{syntax-case}?
512 The examples we have shown thus far could just as well have been expressed with
513 @code{syntax-rules}, and have just shown that @code{syntax-case} is more
514 verbose, which is true. But there is a difference: @code{syntax-case} creates
515 @emph{procedural} macros, giving the full power of Scheme to the macro expander.
516 This has many practical applications.
518 A common desire is to be able to match a form only if it is an identifier. This
519 is impossible with @code{syntax-rules}, given the datum matching forms. But with
520 @code{syntax-case} it is easy:
522 @deffn {Scheme Procedure} identifier? syntax-object
523 Returns @code{#t} iff @var{syntax-object} is an identifier.
527 ;; relying on previous add1 definition
531 ((_ var) (identifier? #'var)
532 #'(set! var (add1 var))))))
537 (add1! "not-an-identifier") @result{} error
540 With @code{syntax-rules}, the error for @code{(add1! "not-an-identifier")} would
541 be something like ``invalid @code{set!}''. With @code{syntax-case}, it will say
542 something like ``invalid @code{add1!}'', because we attach the @dfn{guard
543 clause} to the pattern: @code{(identifier? #'var)}. This becomes more important
544 with more complicated macros. It is necessary to use @code{identifier?}, because
545 to the expander, an identifier is more than a bare symbol.
547 Note that even in the guard clause, we reference the @var{var} pattern variable
548 within a @code{syntax} form, via @code{#'var}.
550 Another common desire is to introduce bindings into the lexical context of the
551 output expression. One example would be in the so-called ``anaphoric macros'',
552 like @code{aif}. Anaphoric macros bind some expression to a well-known
553 identifier, often @code{it}, within their bodies. For example, in @code{(aif
554 (foo) (bar it))}, @code{it} would be bound to the result of @code{(foo)}.
556 To begin with, we should mention a solution that doesn't work:
565 (if it then else))))))
568 The reason that this doesn't work is that, by default, the expander will
569 preserve referential transparency; the @var{then} and @var{else} expressions
570 won't have access to the binding of @code{it}.
572 But they can, if we explicitly introduce a binding via @code{datum->syntax}.
574 @deffn {Scheme Procedure} datum->syntax for-syntax datum
575 Create a syntax object that wraps @var{datum}, within the lexical context
576 corresponding to the syntax object @var{for-syntax}.
579 For completeness, we should mention that it is possible to strip the metadata
580 from a syntax object, returning a raw Scheme datum:
582 @deffn {Scheme Procedure} syntax->datum syntax-object
583 Strip the metadata from @var{syntax-object}, returning its contents as a raw
587 In this case we want to introduce @code{it} in the context of the whole
588 expression, so we can create a syntax object as @code{(datum->syntax x 'it)},
589 where @code{x} is the whole expression, as passed to the transformer procedure.
591 Here's another solution that doesn't work:
594 ;; doesn't work either
599 (let ((it (datum->syntax x 'it)))
601 (if it then else)))))))
604 The reason that this one doesn't work is that there are really two
605 environments at work here -- the environment of pattern variables, as
606 bound by @code{syntax-case}, and the environment of lexical variables,
607 as bound by normal Scheme. The outer let form establishes a binding in
608 the environment of lexical variables, but the inner let form is inside a
609 syntax form, where only pattern variables will be substituted. Here we
610 need to introduce a piece of the lexical environment into the pattern
611 variable environment, and we can do so using @code{syntax-case} itself:
614 ;; works, but is obtuse
619 ;; invoking syntax-case on the generated
620 ;; syntax object to expose it to `syntax'
621 (syntax-case (datum->syntax x 'it) ()
624 (if it then else))))))))
626 (aif (getuid) (display it) (display "none")) (newline)
630 However there are easier ways to write this. @code{with-syntax} is often
633 @deffn {Syntax} with-syntax ((pat val)...) exp...
634 Bind patterns @var{pat} from their corresponding values @var{val}, within the
635 lexical context of @var{exp...}.
643 (with-syntax ((it (datum->syntax x 'it)))
645 (if it then else)))))))
649 As you might imagine, @code{with-syntax} is defined in terms of
650 @code{syntax-case}. But even that might be off-putting to you if you are an old
651 Lisp macro hacker, used to building macro output with @code{quasiquote}. The
652 issue is that @code{with-syntax} creates a separation between the point of
653 definition of a value and its point of substitution.
657 @pindex unsyntax-splicing
658 So for cases in which a @code{quasiquote} style makes more sense,
659 @code{syntax-case} also defines @code{quasisyntax}, and the related
660 @code{unsyntax} and @code{unsyntax-splicing}, abbreviated by the reader as
661 @code{#`}, @code{#,}, and @code{#,@@}, respectively.
663 For example, to define a macro that inserts a compile-time timestamp into a
664 source file, one may write:
667 (define-syntax display-compile-timestamp
672 (display "The compile timestamp was: ")
673 (display #,(current-time))
677 Readers interested in further information on @code{syntax-case} macros should
678 see R. Kent Dybvig's excellent @cite{The Scheme Programming Language}, either
679 edition 3 or 4, in the chapter on syntax. Dybvig was the primary author of the
680 @code{syntax-case} system. The book itself is available online at
681 @uref{http://scheme.com/tspl4/}.
683 @node Syntax Transformer Helpers
684 @subsection Syntax Transformer Helpers
686 As noted in the previous section, Guile's syntax expander operates on
687 syntax objects. Procedural macros consume and produce syntax objects.
688 This section describes some of the auxiliary helpers that procedural
689 macros can use to compare, generate, and query objects of this data
692 @deffn {Scheme Procedure} bound-identifier=? a b
693 Return @code{#t} iff the syntax objects @var{a} and @var{b} refer to the
694 same lexically-bound identifier.
697 @deffn {Scheme Procedure} free-identifier=? a b
698 Return @code{#t} iff the syntax objects @var{a} and @var{b} refer to the
699 same free identifier.
702 @deffn {Scheme Procedure} generate-temporaries ls
703 Return a list of temporary identifiers as long as @var{ls} is long.
706 @deffn {Scheme Procedure} syntax-source x
707 Return the source properties that correspond to the syntax object
708 @var{x}. @xref{Source Properties}, for more information.
711 Guile also offers some more experimental interfaces in a separate
712 module. As was the case with the Large Hadron Collider, it is unclear
713 to our senior macrologists whether adding these interfaces will result
714 in awesomeness or in the destruction of Guile via the creation of a
715 singularity. We will preserve their functionality through the 2.0
716 series, but we reserve the right to modify them in a future stable
717 series, to a more than usual degree.
720 (use-modules (system syntax))
723 @deffn {Scheme Procedure} syntax-module id
724 Return the name of the module whose source contains the identifier
728 @deffn {Scheme Procedure} syntax-local-binding id
729 Resolve the identifer @var{id}, a syntax object, within the current
730 lexical environment, and return two values, the binding type and a
731 binding value. The binding type is a symbol, which may be one of the
736 A lexically-bound variable. The value is a unique token (in the sense
737 of @code{eq?}) identifying this binding.
739 A syntax transformer, either local or global. The value is the
740 transformer procedure.
741 @item pattern-variable
742 A pattern variable, bound via syntax-case. The value is an opaque
743 object, internal to the expander.
744 @item displaced-lexical
745 A lexical variable that has gone out of scope. This can happen if a
746 badly-written procedural macro saves a syntax object, then attempts to
747 introduce it in a context in which it is unbound. The value is
750 A global binding. The value is a pair, whose head is the symbol, and
751 whose tail is the name of the module in which to resolve the symbol.
753 Some other binding, like @code{lambda} or other core bindings. The
757 This is a very low-level procedure, with limited uses. One case in
758 which it is useful is to build abstractions that associate auxiliary
759 information with macros:
762 (define aux-property (make-object-property))
763 (define-syntax-rule (with-aux aux value)
765 (set! (aux-property trans) aux)
767 (define-syntax retrieve-aux
771 (call-with-values (lambda () (syntax-local-binding #'id))
773 (with-syntax ((aux (datum->syntax #'here
774 (and (eq? type 'macro)
775 (aux-property val)))))
779 (syntax-rules () ((_) 'foo))))
786 @code{syntax-local-binding} must be called within the dynamic extent of
787 a syntax transformer; to call it otherwise will signal an error.
790 @deffn {Scheme Procedure} syntax-locally-bound-identifiers id
791 Return a list of identifiers that were visible lexically when the
792 identifier @var{id} was created, in order from outermost to innermost.
794 This procedure is intended to be used in specialized procedural macros,
795 to provide a macro with the set of bound identifiers that the macro can
798 As a technical implementation detail, the identifiers returned by
799 @code{syntax-locally-bound-identifiers} will be anti-marked, like the
800 syntax object that is given as input to a macro. This is to signal to
801 the macro expander that these bindings were present in the original
802 source, and do not need to be hygienically renamed, as would be the case
803 with other introduced identifiers. See the discussion of hygiene in
804 section 12.1 of the R6RS, for more information on marks.
807 (define (local-lexicals id)
809 (eq? (syntax-local-binding x) 'lexical))
810 (syntax-locally-bound-identifiers id)))
811 (define-syntax lexicals
814 ((lexicals) #'(lexicals lexicals))
816 (with-syntax (((id ...) (local-lexicals #'scope)))
817 #'(list (cons 'id id) ...))))))
819 (let* ((x 10) (x 20)) (lexicals))
820 @result{} ((x . 10) (x . 20))
826 @subsection Lisp-style Macro Definitions
828 The traditional way to define macros in Lisp is very similar to procedure
829 definitions. The key differences are that the macro definition body should
830 return a list that describes the transformed expression, and that the definition
831 is marked as a macro definition (rather than a procedure definition) by the use
832 of a different definition keyword: in Lisp, @code{defmacro} rather than
833 @code{defun}, and in Scheme, @code{define-macro} rather than @code{define}.
836 @fnindex define-macro
837 Guile supports this style of macro definition using both @code{defmacro}
838 and @code{define-macro}. The only difference between them is how the
839 macro name and arguments are grouped together in the definition:
842 (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
849 (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
853 The difference is analogous to the corresponding difference between
854 Lisp's @code{defun} and Scheme's @code{define}.
856 Having read the previous section on @code{syntax-case}, it's probably clear that
857 Guile actually implements defmacros in terms of @code{syntax-case}, applying the
858 transformer on the expression between invocations of @code{syntax->datum} and
859 @code{datum->syntax}. This realization leads us to the problem with defmacros,
860 that they do not preserve referential transparency. One can be careful to not
861 introduce bindings into expanded code, via liberal use of @code{gensym}, but
862 there is no getting around the lack of referential transparency for free
863 bindings in the macro itself.
865 Even a macro as simple as our @code{when} from before is difficult to get right:
868 (define-macro (when cond exp . rest)
870 (begin ,exp . ,rest)))
872 (when #f (display "Launching missiles!\n"))
876 (when #f (display "Launching missiles!\n")))
877 @print{} Launching missiles!
878 @result{} (#f #<unspecified>)
881 Guile's perspective is that defmacros have had a good run, but that modern
882 macros should be written with @code{syntax-rules} or @code{syntax-case}. There
883 are still many uses of defmacros within Guile itself, but we will be phasing
884 them out over time. Of course we won't take away @code{defmacro} or
885 @code{define-macro} themselves, as there is lots of code out there that uses
889 @node Identifier Macros
890 @subsection Identifier Macros
892 When the syntax expander sees a form in which the first element is a macro, the
893 whole form gets passed to the macro's syntax transformer. One may visualize this
897 (define-syntax foo foo-transformer)
900 (foo-transformer #'(foo @var{arg}...))
903 If, on the other hand, a macro is referenced in some other part of a form, the
904 syntax transformer is invoked with only the macro reference, not the whole form.
907 (define-syntax foo foo-transformer)
910 (foo-transformer #'foo)
913 This allows bare identifier references to be replaced programmatically via a
914 macro. @code{syntax-rules} provides some syntax to effect this transformation
917 @deffn {Syntax} identifier-syntax exp
918 Returns a macro transformer that will replace occurrences of the macro with
922 For example, if you are importing external code written in terms of @code{fx+},
923 the fixnum addition operator, but Guile doesn't have @code{fx+}, you may use the
924 following to replace @code{fx+} with @code{+}:
927 (define-syntax fx+ (identifier-syntax +))
930 There is also special support for recognizing identifiers on the
931 left-hand side of a @code{set!} expression, as in the following:
934 (define-syntax foo foo-transformer)
937 (foo-transformer #'(set! foo @var{val}))
938 ;; iff foo-transformer is a "variable transformer"
941 As the example notes, the transformer procedure must be explicitly
942 marked as being a ``variable transformer'', as most macros aren't
943 written to discriminate on the form in the operator position.
945 @deffn {Scheme Procedure} make-variable-transformer transformer
946 Mark the @var{transformer} procedure as being a ``variable
947 transformer''. In practice this means that, when bound to a syntactic
948 keyword, it may detect references to that keyword on the left-hand-side
953 (define-syntax bar-alias
954 (make-variable-transformer
956 (syntax-case x (set!)
957 ((set! var val) #'(set! bar val))
958 ((var arg ...) #'(bar arg ...))
959 (var (identifier? #'var) #'bar)))))
961 bar-alias @result{} 10
965 bar-alias @result{} 30
969 There is an extension to identifier-syntax which allows it to handle the
970 @code{set!} case as well:
972 @deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2)
973 Create a variable transformer. The first clause is used for references
974 to the variable in operator or operand position, and the second for
975 appearances of the variable on the left-hand-side of an assignment.
977 For example, the previous @code{bar-alias} example could be expressed
978 more succinctly like this:
981 (define-syntax bar-alias
984 ((set! var val) (set! bar val))))
988 As before, the templates in @code{identifier-syntax} forms do not need
989 wrapping in @code{#'} syntax forms.
993 @node Syntax Parameters
994 @subsection Syntax Parameters
996 Syntax parameters@footnote{Described in the paper @cite{Keeping it Clean
997 with Syntax Parameters} by Barzilay, Culpepper and Flatt.} are a
998 mechanism for rebinding a macro definition within the dynamic extent of
999 a macro expansion. This provides a convenient solution to one of the
1000 most common types of unhygienic macro: those that introduce a unhygienic
1001 binding each time the macro is used. Examples include a @code{lambda}
1002 form with a @code{return} keyword, or class macros that introduce a
1003 special @code{self} binding.
1005 With syntax parameters, instead of introducing the binding
1006 unhygienically each time, we instead create one binding for the keyword,
1007 which we can then adjust later when we want the keyword to have a
1008 different meaning. As no new bindings are introduced, hygiene is
1009 preserved. This is similar to the dynamic binding mechanisms we have at
1010 run-time (@pxref{SRFI-39, parameters}), except that the dynamic binding
1011 only occurs during macro expansion. The code after macro expansion
1012 remains lexically scoped.
1014 @deffn {Syntax} define-syntax-parameter keyword transformer
1015 Binds @var{keyword} to the value obtained by evaluating
1016 @var{transformer}. The @var{transformer} provides the default expansion
1017 for the syntax parameter, and in the absence of
1018 @code{syntax-parameterize}, is functionally equivalent to
1019 @code{define-syntax}. Usually, you will just want to have the
1020 @var{transformer} throw a syntax error indicating that the @var{keyword}
1021 is supposed to be used in conjunction with another macro, for example:
1023 (define-syntax-parameter return
1025 (syntax-violation 'return "return used outside of a lambda^" stx)))
1029 @deffn {Syntax} syntax-parameterize ((keyword transformer) @dots{}) exp @dots{}
1030 Adjusts @var{keyword} @dots{} to use the values obtained by evaluating
1031 their @var{transformer} @dots{}, in the expansion of the @var{exp}
1032 @dots{} forms. Each @var{keyword} must be bound to a syntax-parameter.
1033 @code{syntax-parameterize} differs from @code{let-syntax}, in that the
1034 binding is not shadowed, but adjusted, and so uses of the keyword in the
1035 expansion of @var{exp} @dots{} use the new transformers. This is
1036 somewhat similar to how @code{parameterize} adjusts the values of
1037 regular parameters, rather than creating new bindings.
1040 (define-syntax lambda^
1042 [(lambda^ argument-list body body* ...)
1043 (lambda argument-list
1044 (call-with-current-continuation
1046 ;; In the body we adjust the 'return' keyword so that calls
1047 ;; to 'return' are replaced with calls to the escape
1049 (syntax-parameterize ([return (syntax-rules ()
1050 [(return vals (... ...))
1051 (escape vals (... ...))])])
1052 body body* ...))))]))
1054 ;; Now we can write functions that return early. Here, 'product' will
1055 ;; return immediately if it sees any 0 element.
1069 @subsection Eval-when
1071 As @code{syntax-case} macros have the whole power of Scheme available to them,
1072 they present a problem regarding time: when a macro runs, what parts of the
1073 program are available for the macro to use?
1075 The default answer to this question is that when you import a module (via
1076 @code{define-module} or @code{use-modules}), that module will be loaded up at
1077 expansion-time, as well as at run-time. Additionally, top-level syntactic
1078 definitions within one compilation unit made by @code{define-syntax} are also
1079 evaluated at expansion time, in the order that they appear in the compilation
1082 But if a syntactic definition needs to call out to a normal procedure at
1083 expansion-time, it might well need need special declarations to indicate that
1084 the procedure should be made available at expansion-time.
1086 For example, the following code will work at a REPL, but not in a file:
1090 (use-modules (srfi srfi-19))
1091 (define (date) (date->string (current-date)))
1092 (define-syntax %date (identifier-syntax (date)))
1093 (define *compilation-date* %date)
1096 It works at a REPL because the expressions are evaluated one-by-one, in order,
1097 but if placed in a file, the expressions are expanded one-by-one, but not
1098 evaluated until the compiled file is loaded.
1100 The fix is to use @code{eval-when}.
1103 ;; correct: using eval-when
1104 (use-modules (srfi srfi-19))
1105 (eval-when (compile load eval)
1106 (define (date) (date->string (current-date))))
1107 (define-syntax %date (identifier-syntax (date)))
1108 (define *compilation-date* %date)
1111 @deffn {Syntax} eval-when conditions exp...
1112 Evaluate @var{exp...} under the given @var{conditions}. Valid conditions include
1113 @code{eval}, @code{load}, and @code{compile}. If you need to use
1114 @code{eval-when}, use it with all three conditions, as in the above example.
1115 Other uses of @code{eval-when} may void your warranty or poison your cat.
1118 @node Internal Macros
1119 @subsection Internal Macros
1121 @deffn {Scheme Procedure} make-syntax-transformer name type binding
1122 Construct a syntax transformer object. This is part of Guile's low-level support
1126 @deffn {Scheme Procedure} macro? obj
1127 @deffnx {C Function} scm_macro_p (obj)
1128 Return @code{#t} iff @var{obj} is a syntax transformer.
1130 Note that it's a bit difficult to actually get a macro as a first-class object;
1131 simply naming it (like @code{case}) will produce a syntax error. But it is
1132 possible to get these objects using @code{module-ref}:
1135 (macro? (module-ref (current-module) 'case))
1140 @deffn {Scheme Procedure} macro-type m
1141 @deffnx {C Function} scm_macro_type (m)
1142 Return the @var{type} that was given when @var{m} was constructed, via
1143 @code{make-syntax-transformer}.
1146 @deffn {Scheme Procedure} macro-name m
1147 @deffnx {C Function} scm_macro_name (m)
1148 Return the name of the macro @var{m}.
1151 @deffn {Scheme Procedure} macro-binding m
1152 @deffnx {C Function} scm_macro_binding (m)
1153 Return the binding of the macro @var{m}.
1156 @deffn {Scheme Procedure} macro-transformer m
1157 @deffnx {C Function} scm_macro_transformer (m)
1158 Return the transformer of the macro @var{m}. This will return a procedure, for
1159 which one may ask the docstring. That's the whole reason this section is
1160 documented. Actually a part of the result of @code{macro-binding}.
1165 @c TeX-master: "guile.texi"