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 [#:resolve-syntax-parameters?=#t]
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 syntax-parameter
743 A syntax parameter (@pxref{Syntax Parameters}). By default,
744 @code{syntax-local-binding} will resolve syntax parameters, so that this
745 value will not be returned. Pass @code{#:resolve-syntax-parameters? #f}
746 to indicate that you are interested in syntax parameters. The value is
747 the default transformer procedure, as in @code{macro}.
748 @item pattern-variable
749 A pattern variable, bound via syntax-case. The value is an opaque
750 object, internal to the expander.
751 @item displaced-lexical
752 A lexical variable that has gone out of scope. This can happen if a
753 badly-written procedural macro saves a syntax object, then attempts to
754 introduce it in a context in which it is unbound. The value is
757 A global binding. The value is a pair, whose head is the symbol, and
758 whose tail is the name of the module in which to resolve the symbol.
760 Some other binding, like @code{lambda} or other core bindings. The
764 This is a very low-level procedure, with limited uses. One case in
765 which it is useful is to build abstractions that associate auxiliary
766 information with macros:
769 (define aux-property (make-object-property))
770 (define-syntax-rule (with-aux aux value)
772 (set! (aux-property trans) aux)
774 (define-syntax retrieve-aux
778 (call-with-values (lambda () (syntax-local-binding #'id))
780 (with-syntax ((aux (datum->syntax #'here
781 (and (eq? type 'macro)
782 (aux-property val)))))
786 (syntax-rules () ((_) 'foo))))
793 @code{syntax-local-binding} must be called within the dynamic extent of
794 a syntax transformer; to call it otherwise will signal an error.
797 @deffn {Scheme Procedure} syntax-locally-bound-identifiers id
798 Return a list of identifiers that were visible lexically when the
799 identifier @var{id} was created, in order from outermost to innermost.
801 This procedure is intended to be used in specialized procedural macros,
802 to provide a macro with the set of bound identifiers that the macro can
805 As a technical implementation detail, the identifiers returned by
806 @code{syntax-locally-bound-identifiers} will be anti-marked, like the
807 syntax object that is given as input to a macro. This is to signal to
808 the macro expander that these bindings were present in the original
809 source, and do not need to be hygienically renamed, as would be the case
810 with other introduced identifiers. See the discussion of hygiene in
811 section 12.1 of the R6RS, for more information on marks.
814 (define (local-lexicals id)
816 (eq? (syntax-local-binding x) 'lexical))
817 (syntax-locally-bound-identifiers id)))
818 (define-syntax lexicals
821 ((lexicals) #'(lexicals lexicals))
823 (with-syntax (((id ...) (local-lexicals #'scope)))
824 #'(list (cons 'id id) ...))))))
826 (let* ((x 10) (x 20)) (lexicals))
827 @result{} ((x . 10) (x . 20))
833 @subsection Lisp-style Macro Definitions
835 The traditional way to define macros in Lisp is very similar to procedure
836 definitions. The key differences are that the macro definition body should
837 return a list that describes the transformed expression, and that the definition
838 is marked as a macro definition (rather than a procedure definition) by the use
839 of a different definition keyword: in Lisp, @code{defmacro} rather than
840 @code{defun}, and in Scheme, @code{define-macro} rather than @code{define}.
843 @fnindex define-macro
844 Guile supports this style of macro definition using both @code{defmacro}
845 and @code{define-macro}. The only difference between them is how the
846 macro name and arguments are grouped together in the definition:
849 (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
856 (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
860 The difference is analogous to the corresponding difference between
861 Lisp's @code{defun} and Scheme's @code{define}.
863 Having read the previous section on @code{syntax-case}, it's probably clear that
864 Guile actually implements defmacros in terms of @code{syntax-case}, applying the
865 transformer on the expression between invocations of @code{syntax->datum} and
866 @code{datum->syntax}. This realization leads us to the problem with defmacros,
867 that they do not preserve referential transparency. One can be careful to not
868 introduce bindings into expanded code, via liberal use of @code{gensym}, but
869 there is no getting around the lack of referential transparency for free
870 bindings in the macro itself.
872 Even a macro as simple as our @code{when} from before is difficult to get right:
875 (define-macro (when cond exp . rest)
877 (begin ,exp . ,rest)))
879 (when #f (display "Launching missiles!\n"))
883 (when #f (display "Launching missiles!\n")))
884 @print{} Launching missiles!
885 @result{} (#f #<unspecified>)
888 Guile's perspective is that defmacros have had a good run, but that modern
889 macros should be written with @code{syntax-rules} or @code{syntax-case}. There
890 are still many uses of defmacros within Guile itself, but we will be phasing
891 them out over time. Of course we won't take away @code{defmacro} or
892 @code{define-macro} themselves, as there is lots of code out there that uses
896 @node Identifier Macros
897 @subsection Identifier Macros
899 When the syntax expander sees a form in which the first element is a macro, the
900 whole form gets passed to the macro's syntax transformer. One may visualize this
904 (define-syntax foo foo-transformer)
907 (foo-transformer #'(foo @var{arg}...))
910 If, on the other hand, a macro is referenced in some other part of a form, the
911 syntax transformer is invoked with only the macro reference, not the whole form.
914 (define-syntax foo foo-transformer)
917 (foo-transformer #'foo)
920 This allows bare identifier references to be replaced programmatically via a
921 macro. @code{syntax-rules} provides some syntax to effect this transformation
924 @deffn {Syntax} identifier-syntax exp
925 Returns a macro transformer that will replace occurrences of the macro with
929 For example, if you are importing external code written in terms of @code{fx+},
930 the fixnum addition operator, but Guile doesn't have @code{fx+}, you may use the
931 following to replace @code{fx+} with @code{+}:
934 (define-syntax fx+ (identifier-syntax +))
937 There is also special support for recognizing identifiers on the
938 left-hand side of a @code{set!} expression, as in the following:
941 (define-syntax foo foo-transformer)
944 (foo-transformer #'(set! foo @var{val}))
945 ;; if foo-transformer is a "variable transformer"
948 As the example notes, the transformer procedure must be explicitly
949 marked as being a ``variable transformer'', as most macros aren't
950 written to discriminate on the form in the operator position.
952 @deffn {Scheme Procedure} make-variable-transformer transformer
953 Mark the @var{transformer} procedure as being a ``variable
954 transformer''. In practice this means that, when bound to a syntactic
955 keyword, it may detect references to that keyword on the left-hand-side
960 (define-syntax bar-alias
961 (make-variable-transformer
963 (syntax-case x (set!)
964 ((set! var val) #'(set! bar val))
965 ((var arg ...) #'(bar arg ...))
966 (var (identifier? #'var) #'bar)))))
968 bar-alias @result{} 10
972 bar-alias @result{} 30
976 There is an extension to identifier-syntax which allows it to handle the
977 @code{set!} case as well:
979 @deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2)
980 Create a variable transformer. The first clause is used for references
981 to the variable in operator or operand position, and the second for
982 appearances of the variable on the left-hand-side of an assignment.
984 For example, the previous @code{bar-alias} example could be expressed
985 more succinctly like this:
988 (define-syntax bar-alias
991 ((set! var val) (set! bar val))))
995 As before, the templates in @code{identifier-syntax} forms do not need
996 wrapping in @code{#'} syntax forms.
1000 @node Syntax Parameters
1001 @subsection Syntax Parameters
1003 Syntax parameters@footnote{Described in the paper @cite{Keeping it Clean
1004 with Syntax Parameters} by Barzilay, Culpepper and Flatt.} are a
1005 mechanism for rebinding a macro definition within the dynamic extent of
1006 a macro expansion. This provides a convenient solution to one of the
1007 most common types of unhygienic macro: those that introduce a unhygienic
1008 binding each time the macro is used. Examples include a @code{lambda}
1009 form with a @code{return} keyword, or class macros that introduce a
1010 special @code{self} binding.
1012 With syntax parameters, instead of introducing the binding
1013 unhygienically each time, we instead create one binding for the keyword,
1014 which we can then adjust later when we want the keyword to have a
1015 different meaning. As no new bindings are introduced, hygiene is
1016 preserved. This is similar to the dynamic binding mechanisms we have at
1017 run-time (@pxref{SRFI-39, parameters}), except that the dynamic binding
1018 only occurs during macro expansion. The code after macro expansion
1019 remains lexically scoped.
1021 @deffn {Syntax} define-syntax-parameter keyword transformer
1022 Binds @var{keyword} to the value obtained by evaluating
1023 @var{transformer}. The @var{transformer} provides the default expansion
1024 for the syntax parameter, and in the absence of
1025 @code{syntax-parameterize}, is functionally equivalent to
1026 @code{define-syntax}. Usually, you will just want to have the
1027 @var{transformer} throw a syntax error indicating that the @var{keyword}
1028 is supposed to be used in conjunction with another macro, for example:
1030 (define-syntax-parameter return
1032 (syntax-violation 'return "return used outside of a lambda^" stx)))
1036 @deffn {Syntax} syntax-parameterize ((keyword transformer) @dots{}) exp @dots{}
1037 Adjusts @var{keyword} @dots{} to use the values obtained by evaluating
1038 their @var{transformer} @dots{}, in the expansion of the @var{exp}
1039 @dots{} forms. Each @var{keyword} must be bound to a syntax-parameter.
1040 @code{syntax-parameterize} differs from @code{let-syntax}, in that the
1041 binding is not shadowed, but adjusted, and so uses of the keyword in the
1042 expansion of @var{exp} @dots{} use the new transformers. This is
1043 somewhat similar to how @code{parameterize} adjusts the values of
1044 regular parameters, rather than creating new bindings.
1047 (define-syntax lambda^
1049 [(lambda^ argument-list body body* ...)
1050 (lambda argument-list
1051 (call-with-current-continuation
1053 ;; In the body we adjust the 'return' keyword so that calls
1054 ;; to 'return' are replaced with calls to the escape
1056 (syntax-parameterize ([return (syntax-rules ()
1057 [(return vals (... ...))
1058 (escape vals (... ...))])])
1059 body body* ...))))]))
1061 ;; Now we can write functions that return early. Here, 'product' will
1062 ;; return immediately if it sees any 0 element.
1076 @subsection Eval-when
1078 As @code{syntax-case} macros have the whole power of Scheme available to them,
1079 they present a problem regarding time: when a macro runs, what parts of the
1080 program are available for the macro to use?
1082 The default answer to this question is that when you import a module (via
1083 @code{define-module} or @code{use-modules}), that module will be loaded up at
1084 expansion-time, as well as at run-time. Additionally, top-level syntactic
1085 definitions within one compilation unit made by @code{define-syntax} are also
1086 evaluated at expansion time, in the order that they appear in the compilation
1089 But if a syntactic definition needs to call out to a normal procedure at
1090 expansion-time, it might well need need special declarations to indicate that
1091 the procedure should be made available at expansion-time.
1093 For example, the following code will work at a REPL, but not in a file:
1097 (use-modules (srfi srfi-19))
1098 (define (date) (date->string (current-date)))
1099 (define-syntax %date (identifier-syntax (date)))
1100 (define *compilation-date* %date)
1103 It works at a REPL because the expressions are evaluated one-by-one, in order,
1104 but if placed in a file, the expressions are expanded one-by-one, but not
1105 evaluated until the compiled file is loaded.
1107 The fix is to use @code{eval-when}.
1110 ;; correct: using eval-when
1111 (use-modules (srfi srfi-19))
1112 (eval-when (compile load eval)
1113 (define (date) (date->string (current-date))))
1114 (define-syntax %date (identifier-syntax (date)))
1115 (define *compilation-date* %date)
1118 @deffn {Syntax} eval-when conditions exp...
1119 Evaluate @var{exp...} under the given @var{conditions}. Valid conditions include
1120 @code{eval}, @code{load}, and @code{compile}. If you need to use
1121 @code{eval-when}, use it with all three conditions, as in the above example.
1122 Other uses of @code{eval-when} may void your warranty or poison your cat.
1125 @node Internal Macros
1126 @subsection Internal Macros
1128 @deffn {Scheme Procedure} make-syntax-transformer name type binding
1129 Construct a syntax transformer object. This is part of Guile's low-level support
1133 @deffn {Scheme Procedure} macro? obj
1134 @deffnx {C Function} scm_macro_p (obj)
1135 Return @code{#t} if @var{obj} is a syntax transformer, or @code{#f}
1138 Note that it's a bit difficult to actually get a macro as a first-class object;
1139 simply naming it (like @code{case}) will produce a syntax error. But it is
1140 possible to get these objects using @code{module-ref}:
1143 (macro? (module-ref (current-module) 'case))
1148 @deffn {Scheme Procedure} macro-type m
1149 @deffnx {C Function} scm_macro_type (m)
1150 Return the @var{type} that was given when @var{m} was constructed, via
1151 @code{make-syntax-transformer}.
1154 @deffn {Scheme Procedure} macro-name m
1155 @deffnx {C Function} scm_macro_name (m)
1156 Return the name of the macro @var{m}.
1159 @deffn {Scheme Procedure} macro-binding m
1160 @deffnx {C Function} scm_macro_binding (m)
1161 Return the binding of the macro @var{m}.
1164 @deffn {Scheme Procedure} macro-transformer m
1165 @deffnx {C Function} scm_macro_transformer (m)
1166 Return the transformer of the macro @var{m}. This will return a procedure, for
1167 which one may ask the docstring. That's the whole reason this section is
1168 documented. Actually a part of the result of @code{macro-binding}.
1173 @c TeX-master: "guile.texi"