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, 2013
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} if @var{syntax-object} is an identifier, or @code{#f}
528 ;; relying on previous add1 definition
532 ((_ var) (identifier? #'var)
533 #'(set! var (add1 var))))))
538 (add1! "not-an-identifier") @result{} error
541 With @code{syntax-rules}, the error for @code{(add1! "not-an-identifier")} would
542 be something like ``invalid @code{set!}''. With @code{syntax-case}, it will say
543 something like ``invalid @code{add1!}'', because we attach the @dfn{guard
544 clause} to the pattern: @code{(identifier? #'var)}. This becomes more important
545 with more complicated macros. It is necessary to use @code{identifier?}, because
546 to the expander, an identifier is more than a bare symbol.
548 Note that even in the guard clause, we reference the @var{var} pattern variable
549 within a @code{syntax} form, via @code{#'var}.
551 Another common desire is to introduce bindings into the lexical context of the
552 output expression. One example would be in the so-called ``anaphoric macros'',
553 like @code{aif}. Anaphoric macros bind some expression to a well-known
554 identifier, often @code{it}, within their bodies. For example, in @code{(aif
555 (foo) (bar it))}, @code{it} would be bound to the result of @code{(foo)}.
557 To begin with, we should mention a solution that doesn't work:
566 (if it then else))))))
569 The reason that this doesn't work is that, by default, the expander will
570 preserve referential transparency; the @var{then} and @var{else} expressions
571 won't have access to the binding of @code{it}.
573 But they can, if we explicitly introduce a binding via @code{datum->syntax}.
575 @deffn {Scheme Procedure} datum->syntax for-syntax datum
576 Create a syntax object that wraps @var{datum}, within the lexical context
577 corresponding to the syntax object @var{for-syntax}.
580 For completeness, we should mention that it is possible to strip the metadata
581 from a syntax object, returning a raw Scheme datum:
583 @deffn {Scheme Procedure} syntax->datum syntax-object
584 Strip the metadata from @var{syntax-object}, returning its contents as a raw
588 In this case we want to introduce @code{it} in the context of the whole
589 expression, so we can create a syntax object as @code{(datum->syntax x 'it)},
590 where @code{x} is the whole expression, as passed to the transformer procedure.
592 Here's another solution that doesn't work:
595 ;; doesn't work either
600 (let ((it (datum->syntax x 'it)))
602 (if it then else)))))))
605 The reason that this one doesn't work is that there are really two
606 environments at work here -- the environment of pattern variables, as
607 bound by @code{syntax-case}, and the environment of lexical variables,
608 as bound by normal Scheme. The outer let form establishes a binding in
609 the environment of lexical variables, but the inner let form is inside a
610 syntax form, where only pattern variables will be substituted. Here we
611 need to introduce a piece of the lexical environment into the pattern
612 variable environment, and we can do so using @code{syntax-case} itself:
615 ;; works, but is obtuse
620 ;; invoking syntax-case on the generated
621 ;; syntax object to expose it to `syntax'
622 (syntax-case (datum->syntax x 'it) ()
625 (if it then else))))))))
627 (aif (getuid) (display it) (display "none")) (newline)
631 However there are easier ways to write this. @code{with-syntax} is often
634 @deffn {Syntax} with-syntax ((pat val)...) exp...
635 Bind patterns @var{pat} from their corresponding values @var{val}, within the
636 lexical context of @var{exp...}.
644 (with-syntax ((it (datum->syntax x 'it)))
646 (if it then else)))))))
650 As you might imagine, @code{with-syntax} is defined in terms of
651 @code{syntax-case}. But even that might be off-putting to you if you are an old
652 Lisp macro hacker, used to building macro output with @code{quasiquote}. The
653 issue is that @code{with-syntax} creates a separation between the point of
654 definition of a value and its point of substitution.
658 @pindex unsyntax-splicing
659 So for cases in which a @code{quasiquote} style makes more sense,
660 @code{syntax-case} also defines @code{quasisyntax}, and the related
661 @code{unsyntax} and @code{unsyntax-splicing}, abbreviated by the reader as
662 @code{#`}, @code{#,}, and @code{#,@@}, respectively.
664 For example, to define a macro that inserts a compile-time timestamp into a
665 source file, one may write:
668 (define-syntax display-compile-timestamp
673 (display "The compile timestamp was: ")
674 (display #,(current-time))
678 Readers interested in further information on @code{syntax-case} macros should
679 see R. Kent Dybvig's excellent @cite{The Scheme Programming Language}, either
680 edition 3 or 4, in the chapter on syntax. Dybvig was the primary author of the
681 @code{syntax-case} system. The book itself is available online at
682 @uref{http://scheme.com/tspl4/}.
684 @node Syntax Transformer Helpers
685 @subsection Syntax Transformer Helpers
687 As noted in the previous section, Guile's syntax expander operates on
688 syntax objects. Procedural macros consume and produce syntax objects.
689 This section describes some of the auxiliary helpers that procedural
690 macros can use to compare, generate, and query objects of this data
693 @deffn {Scheme Procedure} bound-identifier=? a b
694 Return @code{#t} if the syntax objects @var{a} and @var{b} refer to the
695 same lexically-bound identifier, or @code{#f} otherwise.
698 @deffn {Scheme Procedure} free-identifier=? a b
699 Return @code{#t} if the syntax objects @var{a} and @var{b} refer to the
700 same free identifier, or @code{#f} otherwise.
703 @deffn {Scheme Procedure} generate-temporaries ls
704 Return a list of temporary identifiers as long as @var{ls} is long.
707 @deffn {Scheme Procedure} syntax-source x
708 Return the source properties that correspond to the syntax object
709 @var{x}. @xref{Source Properties}, for more information.
712 Guile also offers some more experimental interfaces in a separate
713 module. As was the case with the Large Hadron Collider, it is unclear
714 to our senior macrologists whether adding these interfaces will result
715 in awesomeness or in the destruction of Guile via the creation of a
716 singularity. We will preserve their functionality through the 2.0
717 series, but we reserve the right to modify them in a future stable
718 series, to a more than usual degree.
721 (use-modules (system syntax))
724 @deffn {Scheme Procedure} syntax-module id
725 Return the name of the module whose source contains the identifier
729 @deffn {Scheme Procedure} syntax-local-binding id
730 Resolve the identifer @var{id}, a syntax object, within the current
731 lexical environment, and return two values, the binding type and a
732 binding value. The binding type is a symbol, which may be one of the
737 A lexically-bound variable. The value is a unique token (in the sense
738 of @code{eq?}) identifying this binding.
740 A syntax transformer, either local or global. The value is the
741 transformer procedure.
742 @item pattern-variable
743 A pattern variable, bound via syntax-case. The value is an opaque
744 object, internal to the expander.
745 @item displaced-lexical
746 A lexical variable that has gone out of scope. This can happen if a
747 badly-written procedural macro saves a syntax object, then attempts to
748 introduce it in a context in which it is unbound. The value is
751 A global binding. The value is a pair, whose head is the symbol, and
752 whose tail is the name of the module in which to resolve the symbol.
754 Some other binding, like @code{lambda} or other core bindings. The
758 This is a very low-level procedure, with limited uses. One case in
759 which it is useful is to build abstractions that associate auxiliary
760 information with macros:
763 (define aux-property (make-object-property))
764 (define-syntax-rule (with-aux aux value)
766 (set! (aux-property trans) aux)
768 (define-syntax retrieve-aux
772 (call-with-values (lambda () (syntax-local-binding #'id))
774 (with-syntax ((aux (datum->syntax #'here
775 (and (eq? type 'macro)
776 (aux-property val)))))
780 (syntax-rules () ((_) 'foo))))
787 @code{syntax-local-binding} must be called within the dynamic extent of
788 a syntax transformer; to call it otherwise will signal an error.
791 @deffn {Scheme Procedure} syntax-locally-bound-identifiers id
792 Return a list of identifiers that were visible lexically when the
793 identifier @var{id} was created, in order from outermost to innermost.
795 This procedure is intended to be used in specialized procedural macros,
796 to provide a macro with the set of bound identifiers that the macro can
799 As a technical implementation detail, the identifiers returned by
800 @code{syntax-locally-bound-identifiers} will be anti-marked, like the
801 syntax object that is given as input to a macro. This is to signal to
802 the macro expander that these bindings were present in the original
803 source, and do not need to be hygienically renamed, as would be the case
804 with other introduced identifiers. See the discussion of hygiene in
805 section 12.1 of the R6RS, for more information on marks.
808 (define (local-lexicals id)
810 (eq? (syntax-local-binding x) 'lexical))
811 (syntax-locally-bound-identifiers id)))
812 (define-syntax lexicals
815 ((lexicals) #'(lexicals lexicals))
817 (with-syntax (((id ...) (local-lexicals #'scope)))
818 #'(list (cons 'id id) ...))))))
820 (let* ((x 10) (x 20)) (lexicals))
821 @result{} ((x . 10) (x . 20))
827 @subsection Lisp-style Macro Definitions
829 The traditional way to define macros in Lisp is very similar to procedure
830 definitions. The key differences are that the macro definition body should
831 return a list that describes the transformed expression, and that the definition
832 is marked as a macro definition (rather than a procedure definition) by the use
833 of a different definition keyword: in Lisp, @code{defmacro} rather than
834 @code{defun}, and in Scheme, @code{define-macro} rather than @code{define}.
837 @fnindex define-macro
838 Guile supports this style of macro definition using both @code{defmacro}
839 and @code{define-macro}. The only difference between them is how the
840 macro name and arguments are grouped together in the definition:
843 (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
850 (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
854 The difference is analogous to the corresponding difference between
855 Lisp's @code{defun} and Scheme's @code{define}.
857 Having read the previous section on @code{syntax-case}, it's probably clear that
858 Guile actually implements defmacros in terms of @code{syntax-case}, applying the
859 transformer on the expression between invocations of @code{syntax->datum} and
860 @code{datum->syntax}. This realization leads us to the problem with defmacros,
861 that they do not preserve referential transparency. One can be careful to not
862 introduce bindings into expanded code, via liberal use of @code{gensym}, but
863 there is no getting around the lack of referential transparency for free
864 bindings in the macro itself.
866 Even a macro as simple as our @code{when} from before is difficult to get right:
869 (define-macro (when cond exp . rest)
871 (begin ,exp . ,rest)))
873 (when #f (display "Launching missiles!\n"))
877 (when #f (display "Launching missiles!\n")))
878 @print{} Launching missiles!
879 @result{} (#f #<unspecified>)
882 Guile's perspective is that defmacros have had a good run, but that modern
883 macros should be written with @code{syntax-rules} or @code{syntax-case}. There
884 are still many uses of defmacros within Guile itself, but we will be phasing
885 them out over time. Of course we won't take away @code{defmacro} or
886 @code{define-macro} themselves, as there is lots of code out there that uses
890 @node Identifier Macros
891 @subsection Identifier Macros
893 When the syntax expander sees a form in which the first element is a macro, the
894 whole form gets passed to the macro's syntax transformer. One may visualize this
898 (define-syntax foo foo-transformer)
901 (foo-transformer #'(foo @var{arg}...))
904 If, on the other hand, a macro is referenced in some other part of a form, the
905 syntax transformer is invoked with only the macro reference, not the whole form.
908 (define-syntax foo foo-transformer)
911 (foo-transformer #'foo)
914 This allows bare identifier references to be replaced programmatically via a
915 macro. @code{syntax-rules} provides some syntax to effect this transformation
918 @deffn {Syntax} identifier-syntax exp
919 Returns a macro transformer that will replace occurrences of the macro with
923 For example, if you are importing external code written in terms of @code{fx+},
924 the fixnum addition operator, but Guile doesn't have @code{fx+}, you may use the
925 following to replace @code{fx+} with @code{+}:
928 (define-syntax fx+ (identifier-syntax +))
931 There is also special support for recognizing identifiers on the
932 left-hand side of a @code{set!} expression, as in the following:
935 (define-syntax foo foo-transformer)
938 (foo-transformer #'(set! foo @var{val}))
939 ;; if foo-transformer is a "variable transformer"
942 As the example notes, the transformer procedure must be explicitly
943 marked as being a ``variable transformer'', as most macros aren't
944 written to discriminate on the form in the operator position.
946 @deffn {Scheme Procedure} make-variable-transformer transformer
947 Mark the @var{transformer} procedure as being a ``variable
948 transformer''. In practice this means that, when bound to a syntactic
949 keyword, it may detect references to that keyword on the left-hand-side
954 (define-syntax bar-alias
955 (make-variable-transformer
957 (syntax-case x (set!)
958 ((set! var val) #'(set! bar val))
959 ((var arg ...) #'(bar arg ...))
960 (var (identifier? #'var) #'bar)))))
962 bar-alias @result{} 10
966 bar-alias @result{} 30
970 There is an extension to identifier-syntax which allows it to handle the
971 @code{set!} case as well:
973 @deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2)
974 Create a variable transformer. The first clause is used for references
975 to the variable in operator or operand position, and the second for
976 appearances of the variable on the left-hand-side of an assignment.
978 For example, the previous @code{bar-alias} example could be expressed
979 more succinctly like this:
982 (define-syntax bar-alias
985 ((set! var val) (set! bar val))))
989 As before, the templates in @code{identifier-syntax} forms do not need
990 wrapping in @code{#'} syntax forms.
994 @node Syntax Parameters
995 @subsection Syntax Parameters
997 Syntax parameters@footnote{Described in the paper @cite{Keeping it Clean
998 with Syntax Parameters} by Barzilay, Culpepper and Flatt.} are a
999 mechanism for rebinding a macro definition within the dynamic extent of
1000 a macro expansion. This provides a convenient solution to one of the
1001 most common types of unhygienic macro: those that introduce a unhygienic
1002 binding each time the macro is used. Examples include a @code{lambda}
1003 form with a @code{return} keyword, or class macros that introduce a
1004 special @code{self} binding.
1006 With syntax parameters, instead of introducing the binding
1007 unhygienically each time, we instead create one binding for the keyword,
1008 which we can then adjust later when we want the keyword to have a
1009 different meaning. As no new bindings are introduced, hygiene is
1010 preserved. This is similar to the dynamic binding mechanisms we have at
1011 run-time (@pxref{SRFI-39, parameters}), except that the dynamic binding
1012 only occurs during macro expansion. The code after macro expansion
1013 remains lexically scoped.
1015 @deffn {Syntax} define-syntax-parameter keyword transformer
1016 Binds @var{keyword} to the value obtained by evaluating
1017 @var{transformer}. The @var{transformer} provides the default expansion
1018 for the syntax parameter, and in the absence of
1019 @code{syntax-parameterize}, is functionally equivalent to
1020 @code{define-syntax}. Usually, you will just want to have the
1021 @var{transformer} throw a syntax error indicating that the @var{keyword}
1022 is supposed to be used in conjunction with another macro, for example:
1024 (define-syntax-parameter return
1026 (syntax-violation 'return "return used outside of a lambda^" stx)))
1030 @deffn {Syntax} syntax-parameterize ((keyword transformer) @dots{}) exp @dots{}
1031 Adjusts @var{keyword} @dots{} to use the values obtained by evaluating
1032 their @var{transformer} @dots{}, in the expansion of the @var{exp}
1033 @dots{} forms. Each @var{keyword} must be bound to a syntax-parameter.
1034 @code{syntax-parameterize} differs from @code{let-syntax}, in that the
1035 binding is not shadowed, but adjusted, and so uses of the keyword in the
1036 expansion of @var{exp} @dots{} use the new transformers. This is
1037 somewhat similar to how @code{parameterize} adjusts the values of
1038 regular parameters, rather than creating new bindings.
1041 (define-syntax lambda^
1043 [(lambda^ argument-list body body* ...)
1044 (lambda argument-list
1045 (call-with-current-continuation
1047 ;; In the body we adjust the 'return' keyword so that calls
1048 ;; to 'return' are replaced with calls to the escape
1050 (syntax-parameterize ([return (syntax-rules ()
1051 [(return vals (... ...))
1052 (escape vals (... ...))])])
1053 body body* ...))))]))
1055 ;; Now we can write functions that return early. Here, 'product' will
1056 ;; return immediately if it sees any 0 element.
1070 @subsection Eval-when
1072 As @code{syntax-case} macros have the whole power of Scheme available to them,
1073 they present a problem regarding time: when a macro runs, what parts of the
1074 program are available for the macro to use?
1076 The default answer to this question is that when you import a module (via
1077 @code{define-module} or @code{use-modules}), that module will be loaded up at
1078 expansion-time, as well as at run-time. Additionally, top-level syntactic
1079 definitions within one compilation unit made by @code{define-syntax} are also
1080 evaluated at expansion time, in the order that they appear in the compilation
1083 But if a syntactic definition needs to call out to a normal procedure at
1084 expansion-time, it might well need need special declarations to indicate that
1085 the procedure should be made available at expansion-time.
1087 For example, the following code will work at a REPL, but not in a file:
1091 (use-modules (srfi srfi-19))
1092 (define (date) (date->string (current-date)))
1093 (define-syntax %date (identifier-syntax (date)))
1094 (define *compilation-date* %date)
1097 It works at a REPL because the expressions are evaluated one-by-one, in order,
1098 but if placed in a file, the expressions are expanded one-by-one, but not
1099 evaluated until the compiled file is loaded.
1101 The fix is to use @code{eval-when}.
1104 ;; correct: using eval-when
1105 (use-modules (srfi srfi-19))
1106 (eval-when (compile load eval)
1107 (define (date) (date->string (current-date))))
1108 (define-syntax %date (identifier-syntax (date)))
1109 (define *compilation-date* %date)
1112 @deffn {Syntax} eval-when conditions exp...
1113 Evaluate @var{exp...} under the given @var{conditions}. Valid conditions include
1114 @code{eval}, @code{load}, and @code{compile}. If you need to use
1115 @code{eval-when}, use it with all three conditions, as in the above example.
1116 Other uses of @code{eval-when} may void your warranty or poison your cat.
1119 @node Internal Macros
1120 @subsection Internal Macros
1122 @deffn {Scheme Procedure} make-syntax-transformer name type binding
1123 Construct a syntax transformer object. This is part of Guile's low-level support
1127 @deffn {Scheme Procedure} macro? obj
1128 @deffnx {C Function} scm_macro_p (obj)
1129 Return @code{#t} if @var{obj} is a syntax transformer, or @code{#f}
1132 Note that it's a bit difficult to actually get a macro as a first-class object;
1133 simply naming it (like @code{case}) will produce a syntax error. But it is
1134 possible to get these objects using @code{module-ref}:
1137 (macro? (module-ref (current-module) 'case))
1142 @deffn {Scheme Procedure} macro-type m
1143 @deffnx {C Function} scm_macro_type (m)
1144 Return the @var{type} that was given when @var{m} was constructed, via
1145 @code{make-syntax-transformer}.
1148 @deffn {Scheme Procedure} macro-name m
1149 @deffnx {C Function} scm_macro_name (m)
1150 Return the name of the macro @var{m}.
1153 @deffn {Scheme Procedure} macro-binding m
1154 @deffnx {C Function} scm_macro_binding (m)
1155 Return the binding of the macro @var{m}.
1158 @deffn {Scheme Procedure} macro-transformer m
1159 @deffnx {C Function} scm_macro_transformer (m)
1160 Return the transformer of the macro @var{m}. This will return a procedure, for
1161 which one may ask the docstring. That's the whole reason this section is
1162 documented. Actually a part of the result of @code{macro-binding}.
1167 @c TeX-master: "guile.texi"