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,
4 @c 2012, 2013, 2014 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 * Macro Expansion:: Procedurally expanding macros.
47 * Hygiene and the Top-Level:: A hack you might want to know about.
48 * Internal Macros:: Macros as first-class values.
52 @subsection Defining Macros
54 A macro is a binding between a keyword and a syntax transformer. Since it's
55 difficult to discuss @code{define-syntax} without discussing the format of
56 transformers, consider the following example macro definition:
61 ((when condition exp ...)
67 (display "let's go\n"))
72 In this example, the @code{when} binding is bound with @code{define-syntax}.
73 Syntax transformers are discussed in more depth in @ref{Syntax Rules} and
76 @deffn {Syntax} define-syntax keyword transformer
77 Bind @var{keyword} to the syntax transformer obtained by evaluating
80 After a macro has been defined, further instances of @var{keyword} in Scheme
81 source code will invoke the syntax transformer defined by @var{transformer}.
84 One can also establish local syntactic bindings with @code{let-syntax}.
86 @deffn {Syntax} let-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{}
87 Bind each @var{keyword} to its corresponding @var{transformer} while
88 expanding @var{exp1} @var{exp2} @enddots{}.
90 A @code{let-syntax} binding only exists at expansion-time.
95 ((unless condition exp ...)
101 @result{} "rock rock rock"
105 A @code{define-syntax} form is valid anywhere a definition may appear: at the
106 top-level, or locally. Just as a local @code{define} expands out to an instance
107 of @code{letrec}, a local @code{define-syntax} expands out to
108 @code{letrec-syntax}.
110 @deffn {Syntax} letrec-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{}
111 Bind each @var{keyword} to its corresponding @var{transformer} while
112 expanding @var{exp1} @var{exp2} @enddots{}.
114 In the spirit of @code{letrec} versus @code{let}, an expansion produced by
115 @var{transformer} may reference a @var{keyword} bound by the
116 same @var{letrec-syntax}.
119 (letrec-syntax ((my-or
125 ((my-or exp rest ...)
129 (my-or rest ...)))))))
130 (my-or #f "rockaway beach"))
131 @result{} "rockaway beach"
136 @subsection Syntax-rules Macros
138 @code{syntax-rules} macros are simple, pattern-driven syntax transformers, with
139 a beauty worthy of Scheme.
141 @deffn {Syntax} syntax-rules literals (pattern template) @dots{}
142 Create a syntax transformer that will rewrite an expression using the rules
143 embodied in the @var{pattern} and @var{template} clauses.
146 A @code{syntax-rules} macro consists of three parts: the literals (if any), the
147 patterns, and as many templates as there are patterns.
149 When the syntax expander sees the invocation of a @code{syntax-rules} macro, it
150 matches the expression against the patterns, in order, and rewrites the
151 expression using the template from the first matching pattern. If no pattern
152 matches, a syntax error is signalled.
154 @subsubsection Patterns
156 We have already seen some examples of patterns in the previous section:
157 @code{(unless condition exp ...)}, @code{(my-or exp)}, and so on. A pattern is
158 structured like the expression that it is to match. It can have nested structure
159 as well, like @code{(let ((var val) ...) exp exp* ...)}. Broadly speaking,
160 patterns are made of lists, improper lists, vectors, identifiers, and datums.
161 Users can match a sequence of patterns using the ellipsis (@code{...}).
163 Identifiers in a pattern are called @dfn{literals} if they are present in the
164 @code{syntax-rules} literals list, and @dfn{pattern variables} otherwise. When
165 building up the macro output, the expander replaces instances of a pattern
166 variable in the template with the matched subexpression.
174 @result{} (foo . bar)
177 An improper list of patterns matches as rest arguments do:
182 ((_ (var val) . exps)
183 (let ((var val)) . exps))))
186 However this definition of @code{let1} probably isn't what you want, as the tail
187 pattern @var{exps} will match non-lists, like @code{(let1 (foo 'bar) . baz)}. So
188 often instead of using improper lists as patterns, ellipsized patterns are
189 better. Instances of a pattern variable in the template must be followed by an
195 ((_ (var val) exp ...)
196 (let ((var val)) exp ...))))
199 This @code{let1} probably still doesn't do what we want, because the body
200 matches sequences of zero expressions, like @code{(let1 (foo 'bar))}. In this
201 case we need to assert we have at least one body expression. A common idiom for
202 this is to name the ellipsized pattern variable with an asterisk:
207 ((_ (var val) exp exp* ...)
208 (let ((var val)) exp exp* ...))))
211 A vector of patterns matches a vector whose contents match the patterns,
212 including ellipsizing and tail patterns.
217 ((_ #((var val) ...) exp exp* ...)
218 (let ((var val) ...) exp exp* ...))))
219 (letv #((foo 'bar)) foo)
223 Literals are used to match specific datums in an expression, like the use of
224 @code{=>} and @code{else} in @code{cond} expressions.
228 (syntax-rules (=> else)
231 (if exp (fun exp) #f)))
232 ((cond1 test exp exp* ...)
233 (if test (begin exp exp* ...)))
234 ((cond1 else exp exp* ...)
235 (begin exp exp* ...))))
237 (define (square x) (* x x))
241 (cond1 10 => square))
242 @result{} #<procedure square (x)>
245 A literal matches an input expression if the input expression is an identifier
246 with the same name as the literal, and both are unbound@footnote{Language
247 lawyers probably see the need here for use of @code{literal-identifier=?} rather
248 than @code{free-identifier=?}, and would probably be correct. Patches
251 If a pattern is not a list, vector, or an identifier, it matches as a literal,
255 (define-syntax define-matcher-macro
263 (define-matcher-macro is-literal-foo? "foo")
265 (is-literal-foo? "foo")
267 (is-literal-foo? "bar")
270 (is-literal-foo? foo))
274 The last example indicates that matching happens at expansion-time, not
277 Syntax-rules macros are always used as @code{(@var{macro} . @var{args})}, and
278 the @var{macro} will always be a symbol. Correspondingly, a @code{syntax-rules}
279 pattern must be a list (proper or improper), and the first pattern in that list
280 must be an identifier. Incidentally it can be any identifier -- it doesn't have
281 to actually be the name of the macro. Thus the following three are equivalent:
287 (if c (begin e ...)))))
292 (if c (begin e ...)))))
296 ((something-else-entirely c e ...)
297 (if c (begin e ...)))))
300 For clarity, use one of the first two variants. Also note that since the pattern
301 variable will always match the macro itself (e.g., @code{cond1}), it is actually
302 left unbound in the template.
304 @subsubsection Hygiene
306 @code{syntax-rules} macros have a magical property: they preserve referential
307 transparency. When you read a macro definition, any free bindings in that macro
308 are resolved relative to the macro definition; and when you read a macro
309 instantiation, all free bindings in that expression are resolved relative to the
312 This property is sometimes known as @dfn{hygiene}, and it does aid in code
313 cleanliness. In your macro definitions, you can feel free to introduce temporary
314 variables, without worrying about inadvertently introducing bindings into the
317 Consider the definition of @code{my-or} from the previous section:
326 ((my-or exp rest ...)
330 (my-or rest ...))))))
333 A naive expansion of @code{(let ((t #t)) (my-or #f t))} would yield:
343 Which clearly is not what we want. Somehow the @code{t} in the definition is
344 distinct from the @code{t} at the site of use; and it is indeed this distinction
345 that is maintained by the syntax expander, when expanding hygienic macros.
347 This discussion is mostly relevant in the context of traditional Lisp macros
348 (@pxref{Defmacros}), which do not preserve referential transparency. Hygiene
349 adds to the expressive power of Scheme.
351 @subsubsection Shorthands
353 One often ends up writing simple one-clause @code{syntax-rules} macros.
354 There is a convenient shorthand for this idiom, in the form of
355 @code{define-syntax-rule}.
357 @deffn {Syntax} define-syntax-rule (keyword . pattern) [docstring] template
358 Define @var{keyword} as a new @code{syntax-rules} macro with one clause.
361 Cast into this form, our @code{when} example is significantly shorter:
364 (define-syntax-rule (when c e ...)
365 (if c (begin e ...)))
368 @subsubsection Reporting Syntax Errors in Macros
370 @deffn {Syntax} syntax-error message [arg ...]
371 Report an error at macro-expansion time. @var{message} must be a string
372 literal, and the optional @var{arg} operands can be arbitrary expressions
373 providing additional information.
376 @code{syntax-error} is intended to be used within @code{syntax-rules}
377 templates. For example:
380 (define-syntax simple-let
382 ((_ (head ... ((x . y) val) . tail)
385 "expected an identifier but got"
387 ((_ ((name val) ...) body1 body2 ...)
388 ((lambda (name ...) body1 body2 ...)
392 @subsubsection Specifying a Custom Ellipsis Identifier
394 When writing macros that generate macro definitions, it is convenient to
395 use a different ellipsis identifier at each level. Guile allows the
396 desired ellipsis identifier to be specified as the first operand to
397 @code{syntax-rules}, as specified by SRFI-46 and R7RS. For example:
400 (define-syntax define-quotation-macros
402 ((_ (macro-name head-symbol) ...)
403 (begin (define-syntax macro-name
406 (quote (head-symbol x :::)))))
408 (define-quotation-macros (quote-a a) (quote-b b) (quote-c c))
409 (quote-a 1 2 3) @result{} (a 1 2 3)
412 @subsubsection Further Information
414 For a formal definition of @code{syntax-rules} and its pattern language, see
415 @xref{Macros, , Macros, r5rs, Revised(5) Report on the Algorithmic Language
418 @code{syntax-rules} macros are simple and clean, but do they have limitations.
419 They do not lend themselves to expressive error messages: patterns either match
420 or they don't. Their ability to generate code is limited to template-driven
421 expansion; often one needs to define a number of helper macros to get real work
422 done. Sometimes one wants to introduce a binding into the lexical context of the
423 generated code; this is impossible with @code{syntax-rules}. Relatedly, they
424 cannot programmatically generate identifiers.
426 The solution to all of these problems is to use @code{syntax-case} if you need
427 its features. But if for some reason you're stuck with @code{syntax-rules}, you
428 might enjoy Joe Marshall's
429 @uref{http://sites.google.com/site/evalapply/eccentric.txt,@code{syntax-rules}
430 Primer for the Merely Eccentric}.
433 @subsection Support for the @code{syntax-case} System
435 @code{syntax-case} macros are procedural syntax transformers, with a power
438 @deffn {Syntax} syntax-case syntax literals (pattern [guard] exp) @dots{}
439 Match the syntax object @var{syntax} against the given patterns, in order. If a
440 @var{pattern} matches, return the result of evaluating the associated @var{exp}.
443 Compare the following definitions of @code{when}:
449 (if test (begin e e* ...)))))
455 #'(if test (begin e e* ...))))))
458 Clearly, the @code{syntax-case} definition is similar to its @code{syntax-rules}
459 counterpart, and equally clearly there are some differences. The
460 @code{syntax-case} definition is wrapped in a @code{lambda}, a function of one
461 argument; that argument is passed to the @code{syntax-case} invocation; and the
462 ``return value'' of the macro has a @code{#'} prefix.
464 All of these differences stem from the fact that @code{syntax-case} does not
465 define a syntax transformer itself -- instead, @code{syntax-case} expressions
466 provide a way to destructure a @dfn{syntax object}, and to rebuild syntax
469 So the @code{lambda} wrapper is simply a leaky implementation detail, that
470 syntax transformers are just functions that transform syntax to syntax. This
471 should not be surprising, given that we have already described macros as
472 ``programs that write programs''. @code{syntax-case} is simply a way to take
473 apart and put together program text, and to be a valid syntax transformer it
474 needs to be wrapped in a procedure.
476 Unlike traditional Lisp macros (@pxref{Defmacros}), @code{syntax-case} macros
477 transform syntax objects, not raw Scheme forms. Recall the naive expansion of
478 @code{my-or} given in the previous section:
489 Raw Scheme forms simply don't have enough information to distinguish the first
490 two @code{t} instances in @code{(if t t t)} from the third @code{t}. So instead
491 of representing identifiers as symbols, the syntax expander represents
492 identifiers as annotated syntax objects, attaching such information to those
493 syntax objects as is needed to maintain referential transparency.
495 @deffn {Syntax} syntax form
496 Create a syntax object wrapping @var{form} within the current lexical context.
499 Syntax objects are typically created internally to the process of expansion, but
500 it is possible to create them outside of syntax expansion:
503 (syntax (foo bar baz))
504 @result{} #<some representation of that syntax>
508 However it is more common, and useful, to create syntax objects when building
509 output from a @code{syntax-case} expression.
516 (syntax (+ exp 1))))))
519 It is not strictly necessary for a @code{syntax-case} expression to return a
520 syntax object, because @code{syntax-case} expressions can be used in helper
521 functions, or otherwise used outside of syntax expansion itself. However a
522 syntax transformer procedure must return a syntax object, so most uses of
523 @code{syntax-case} do end up returning syntax objects.
525 Here in this case, the form that built the return value was @code{(syntax (+ exp
526 1))}. The interesting thing about this is that within a @code{syntax}
527 expression, any appearance of a pattern variable is substituted into the
528 resulting syntax object, carrying with it all relevant metadata from the source
529 expression, such as lexical identity and source location.
531 Indeed, a pattern variable may only be referenced from inside a @code{syntax}
532 form. The syntax expander would raise an error when defining @code{add1} if it
533 found @var{exp} referenced outside a @code{syntax} form.
535 Since @code{syntax} appears frequently in macro-heavy code, it has a special
536 reader macro: @code{#'}. @code{#'foo} is transformed by the reader into
537 @code{(syntax foo)}, just as @code{'foo} is transformed into @code{(quote foo)}.
539 The pattern language used by @code{syntax-case} is conveniently the same
540 language used by @code{syntax-rules}. Given this, Guile actually defines
541 @code{syntax-rules} in terms of @code{syntax-case}:
544 (define-syntax syntax-rules
547 ((_ (k ...) ((keyword . pattern) template) ...)
549 (syntax-case x (k ...)
550 ((dummy . pattern) #'template)
556 @subsubsection Why @code{syntax-case}?
558 The examples we have shown thus far could just as well have been expressed with
559 @code{syntax-rules}, and have just shown that @code{syntax-case} is more
560 verbose, which is true. But there is a difference: @code{syntax-case} creates
561 @emph{procedural} macros, giving the full power of Scheme to the macro expander.
562 This has many practical applications.
564 A common desire is to be able to match a form only if it is an identifier. This
565 is impossible with @code{syntax-rules}, given the datum matching forms. But with
566 @code{syntax-case} it is easy:
568 @deffn {Scheme Procedure} identifier? syntax-object
569 Returns @code{#t} if @var{syntax-object} is an identifier, or @code{#f}
574 ;; relying on previous add1 definition
578 ((_ var) (identifier? #'var)
579 #'(set! var (add1 var))))))
584 (add1! "not-an-identifier") @result{} error
587 With @code{syntax-rules}, the error for @code{(add1! "not-an-identifier")} would
588 be something like ``invalid @code{set!}''. With @code{syntax-case}, it will say
589 something like ``invalid @code{add1!}'', because we attach the @dfn{guard
590 clause} to the pattern: @code{(identifier? #'var)}. This becomes more important
591 with more complicated macros. It is necessary to use @code{identifier?}, because
592 to the expander, an identifier is more than a bare symbol.
594 Note that even in the guard clause, we reference the @var{var} pattern variable
595 within a @code{syntax} form, via @code{#'var}.
597 Another common desire is to introduce bindings into the lexical context of the
598 output expression. One example would be in the so-called ``anaphoric macros'',
599 like @code{aif}. Anaphoric macros bind some expression to a well-known
600 identifier, often @code{it}, within their bodies. For example, in @code{(aif
601 (foo) (bar it))}, @code{it} would be bound to the result of @code{(foo)}.
603 To begin with, we should mention a solution that doesn't work:
612 (if it then else))))))
615 The reason that this doesn't work is that, by default, the expander will
616 preserve referential transparency; the @var{then} and @var{else} expressions
617 won't have access to the binding of @code{it}.
619 But they can, if we explicitly introduce a binding via @code{datum->syntax}.
621 @deffn {Scheme Procedure} datum->syntax for-syntax datum
622 Create a syntax object that wraps @var{datum}, within the lexical context
623 corresponding to the syntax object @var{for-syntax}.
626 For completeness, we should mention that it is possible to strip the metadata
627 from a syntax object, returning a raw Scheme datum:
629 @deffn {Scheme Procedure} syntax->datum syntax-object
630 Strip the metadata from @var{syntax-object}, returning its contents as a raw
634 In this case we want to introduce @code{it} in the context of the whole
635 expression, so we can create a syntax object as @code{(datum->syntax x 'it)},
636 where @code{x} is the whole expression, as passed to the transformer procedure.
638 Here's another solution that doesn't work:
641 ;; doesn't work either
646 (let ((it (datum->syntax x 'it)))
648 (if it then else)))))))
651 The reason that this one doesn't work is that there are really two
652 environments at work here -- the environment of pattern variables, as
653 bound by @code{syntax-case}, and the environment of lexical variables,
654 as bound by normal Scheme. The outer let form establishes a binding in
655 the environment of lexical variables, but the inner let form is inside a
656 syntax form, where only pattern variables will be substituted. Here we
657 need to introduce a piece of the lexical environment into the pattern
658 variable environment, and we can do so using @code{syntax-case} itself:
661 ;; works, but is obtuse
666 ;; invoking syntax-case on the generated
667 ;; syntax object to expose it to `syntax'
668 (syntax-case (datum->syntax x 'it) ()
671 (if it then else))))))))
673 (aif (getuid) (display it) (display "none")) (newline)
677 However there are easier ways to write this. @code{with-syntax} is often
680 @deffn {Syntax} with-syntax ((pat val) @dots{}) exp @dots{}
681 Bind patterns @var{pat} from their corresponding values @var{val}, within the
682 lexical context of @var{exp} @enddots{}.
690 (with-syntax ((it (datum->syntax x 'it)))
692 (if it then else)))))))
696 As you might imagine, @code{with-syntax} is defined in terms of
697 @code{syntax-case}. But even that might be off-putting to you if you are an old
698 Lisp macro hacker, used to building macro output with @code{quasiquote}. The
699 issue is that @code{with-syntax} creates a separation between the point of
700 definition of a value and its point of substitution.
704 @pindex unsyntax-splicing
705 So for cases in which a @code{quasiquote} style makes more sense,
706 @code{syntax-case} also defines @code{quasisyntax}, and the related
707 @code{unsyntax} and @code{unsyntax-splicing}, abbreviated by the reader as
708 @code{#`}, @code{#,}, and @code{#,@@}, respectively.
710 For example, to define a macro that inserts a compile-time timestamp into a
711 source file, one may write:
714 (define-syntax display-compile-timestamp
719 (display "The compile timestamp was: ")
720 (display #,(current-time))
724 Readers interested in further information on @code{syntax-case} macros should
725 see R. Kent Dybvig's excellent @cite{The Scheme Programming Language}, either
726 edition 3 or 4, in the chapter on syntax. Dybvig was the primary author of the
727 @code{syntax-case} system. The book itself is available online at
728 @uref{http://scheme.com/tspl4/}.
730 @subsubsection Custom Ellipsis Identifiers for syntax-case Macros
732 When writing procedural macros that generate macro definitions, it is
733 convenient to use a different ellipsis identifier at each level. Guile
734 supports this for procedural macros using the @code{with-ellipsis}
737 @deffn {Syntax} with-ellipsis ellipsis body @dots{}
738 @var{ellipsis} must be an identifier. Evaluate @var{body} in a special
739 lexical environment such that all macro patterns and templates within
740 @var{body} will use @var{ellipsis} as the ellipsis identifier instead of
741 the usual three dots (@code{...}).
747 (define-syntax define-quotation-macros
750 ((_ (macro-name head-symbol) ...)
751 #'(begin (define-syntax macro-name
756 #'(quote (head-symbol x :::)))))))
758 (define-quotation-macros (quote-a a) (quote-b b) (quote-c c))
759 (quote-a 1 2 3) @result{} (a 1 2 3)
762 Note that @code{with-ellipsis} does not affect the ellipsis identifier
763 of the generated code, unless @code{with-ellipsis} is included around
766 @node Syntax Transformer Helpers
767 @subsection Syntax Transformer Helpers
769 As noted in the previous section, Guile's syntax expander operates on
770 syntax objects. Procedural macros consume and produce syntax objects.
771 This section describes some of the auxiliary helpers that procedural
772 macros can use to compare, generate, and query objects of this data
775 @deffn {Scheme Procedure} bound-identifier=? a b
776 Return @code{#t} if the syntax objects @var{a} and @var{b} refer to the
777 same lexically-bound identifier, or @code{#f} otherwise.
780 @deffn {Scheme Procedure} free-identifier=? a b
781 Return @code{#t} if the syntax objects @var{a} and @var{b} refer to the
782 same free identifier, or @code{#f} otherwise.
785 @deffn {Scheme Procedure} generate-temporaries ls
786 Return a list of temporary identifiers as long as @var{ls} is long.
789 @deffn {Scheme Procedure} syntax-source x
790 Return the source properties that correspond to the syntax object
791 @var{x}. @xref{Source Properties}, for more information.
794 Guile also offers some more experimental interfaces in a separate
795 module. As was the case with the Large Hadron Collider, it is unclear
796 to our senior macrologists whether adding these interfaces will result
797 in awesomeness or in the destruction of Guile via the creation of a
798 singularity. We will preserve their functionality through the 2.0
799 series, but we reserve the right to modify them in a future stable
800 series, to a more than usual degree.
803 (use-modules (system syntax))
806 @deffn {Scheme Procedure} syntax-module id
807 Return the name of the module whose source contains the identifier
811 @deffn {Scheme Procedure} syntax-local-binding id [#:resolve-syntax-parameters?=#t]
812 Resolve the identifer @var{id}, a syntax object, within the current
813 lexical environment, and return two values, the binding type and a
814 binding value. The binding type is a symbol, which may be one of the
819 A lexically-bound variable. The value is a unique token (in the sense
820 of @code{eq?}) identifying this binding.
822 A syntax transformer, either local or global. The value is the
823 transformer procedure.
824 @item syntax-parameter
825 A syntax parameter (@pxref{Syntax Parameters}). By default,
826 @code{syntax-local-binding} will resolve syntax parameters, so that this
827 value will not be returned. Pass @code{#:resolve-syntax-parameters? #f}
828 to indicate that you are interested in syntax parameters. The value is
829 the default transformer procedure, as in @code{macro}.
830 @item pattern-variable
831 A pattern variable, bound via @code{syntax-case}. The value is an
832 opaque object, internal to the expander.
834 An internal binding, bound via @code{with-ellipsis}. The value is the
835 (anti-marked) local ellipsis identifier.
836 @item displaced-lexical
837 A lexical variable that has gone out of scope. This can happen if a
838 badly-written procedural macro saves a syntax object, then attempts to
839 introduce it in a context in which it is unbound. The value is
842 A global binding. The value is a pair, whose head is the symbol, and
843 whose tail is the name of the module in which to resolve the symbol.
845 Some other binding, like @code{lambda} or other core bindings. The
849 This is a very low-level procedure, with limited uses. One case in
850 which it is useful is to build abstractions that associate auxiliary
851 information with macros:
854 (define aux-property (make-object-property))
855 (define-syntax-rule (with-aux aux value)
857 (set! (aux-property trans) aux)
859 (define-syntax retrieve-aux
863 (call-with-values (lambda () (syntax-local-binding #'id))
865 (with-syntax ((aux (datum->syntax #'here
866 (and (eq? type 'macro)
867 (aux-property val)))))
871 (syntax-rules () ((_) 'foo))))
878 @code{syntax-local-binding} must be called within the dynamic extent of
879 a syntax transformer; to call it otherwise will signal an error.
882 @deffn {Scheme Procedure} syntax-locally-bound-identifiers id
883 Return a list of identifiers that were visible lexically when the
884 identifier @var{id} was created, in order from outermost to innermost.
886 This procedure is intended to be used in specialized procedural macros,
887 to provide a macro with the set of bound identifiers that the macro can
890 As a technical implementation detail, the identifiers returned by
891 @code{syntax-locally-bound-identifiers} will be anti-marked, like the
892 syntax object that is given as input to a macro. This is to signal to
893 the macro expander that these bindings were present in the original
894 source, and do not need to be hygienically renamed, as would be the case
895 with other introduced identifiers. See the discussion of hygiene in
896 section 12.1 of the R6RS, for more information on marks.
899 (define (local-lexicals id)
901 (eq? (syntax-local-binding x) 'lexical))
902 (syntax-locally-bound-identifiers id)))
903 (define-syntax lexicals
906 ((lexicals) #'(lexicals lexicals))
908 (with-syntax (((id ...) (local-lexicals #'scope)))
909 #'(list (cons 'id id) ...))))))
911 (let* ((x 10) (x 20)) (lexicals))
912 @result{} ((x . 10) (x . 20))
918 @subsection Lisp-style Macro Definitions
920 The traditional way to define macros in Lisp is very similar to procedure
921 definitions. The key differences are that the macro definition body should
922 return a list that describes the transformed expression, and that the definition
923 is marked as a macro definition (rather than a procedure definition) by the use
924 of a different definition keyword: in Lisp, @code{defmacro} rather than
925 @code{defun}, and in Scheme, @code{define-macro} rather than @code{define}.
928 @fnindex define-macro
929 Guile supports this style of macro definition using both @code{defmacro}
930 and @code{define-macro}. The only difference between them is how the
931 macro name and arguments are grouped together in the definition:
934 (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
941 (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
945 The difference is analogous to the corresponding difference between
946 Lisp's @code{defun} and Scheme's @code{define}.
948 Having read the previous section on @code{syntax-case}, it's probably clear that
949 Guile actually implements defmacros in terms of @code{syntax-case}, applying the
950 transformer on the expression between invocations of @code{syntax->datum} and
951 @code{datum->syntax}. This realization leads us to the problem with defmacros,
952 that they do not preserve referential transparency. One can be careful to not
953 introduce bindings into expanded code, via liberal use of @code{gensym}, but
954 there is no getting around the lack of referential transparency for free
955 bindings in the macro itself.
957 Even a macro as simple as our @code{when} from before is difficult to get right:
960 (define-macro (when cond exp . rest)
962 (begin ,exp . ,rest)))
964 (when #f (display "Launching missiles!\n"))
968 (when #f (display "Launching missiles!\n")))
969 @print{} Launching missiles!
970 @result{} (#f #<unspecified>)
973 Guile's perspective is that defmacros have had a good run, but that modern
974 macros should be written with @code{syntax-rules} or @code{syntax-case}. There
975 are still many uses of defmacros within Guile itself, but we will be phasing
976 them out over time. Of course we won't take away @code{defmacro} or
977 @code{define-macro} themselves, as there is lots of code out there that uses
981 @node Identifier Macros
982 @subsection Identifier Macros
984 When the syntax expander sees a form in which the first element is a macro, the
985 whole form gets passed to the macro's syntax transformer. One may visualize this
989 (define-syntax foo foo-transformer)
992 (foo-transformer #'(foo @var{arg}...))
995 If, on the other hand, a macro is referenced in some other part of a form, the
996 syntax transformer is invoked with only the macro reference, not the whole form.
999 (define-syntax foo foo-transformer)
1002 (foo-transformer #'foo)
1005 This allows bare identifier references to be replaced programmatically via a
1006 macro. @code{syntax-rules} provides some syntax to effect this transformation
1009 @deffn {Syntax} identifier-syntax exp
1010 Returns a macro transformer that will replace occurrences of the macro with
1014 For example, if you are importing external code written in terms of @code{fx+},
1015 the fixnum addition operator, but Guile doesn't have @code{fx+}, you may use the
1016 following to replace @code{fx+} with @code{+}:
1019 (define-syntax fx+ (identifier-syntax +))
1022 There is also special support for recognizing identifiers on the
1023 left-hand side of a @code{set!} expression, as in the following:
1026 (define-syntax foo foo-transformer)
1027 (set! foo @var{val})
1029 (foo-transformer #'(set! foo @var{val}))
1030 ;; if foo-transformer is a "variable transformer"
1033 As the example notes, the transformer procedure must be explicitly
1034 marked as being a ``variable transformer'', as most macros aren't
1035 written to discriminate on the form in the operator position.
1037 @deffn {Scheme Procedure} make-variable-transformer transformer
1038 Mark the @var{transformer} procedure as being a ``variable
1039 transformer''. In practice this means that, when bound to a syntactic
1040 keyword, it may detect references to that keyword on the left-hand-side
1045 (define-syntax bar-alias
1046 (make-variable-transformer
1048 (syntax-case x (set!)
1049 ((set! var val) #'(set! bar val))
1050 ((var arg ...) #'(bar arg ...))
1051 (var (identifier? #'var) #'bar)))))
1053 bar-alias @result{} 10
1057 bar-alias @result{} 30
1061 There is an extension to identifier-syntax which allows it to handle the
1062 @code{set!} case as well:
1064 @deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2)
1065 Create a variable transformer. The first clause is used for references
1066 to the variable in operator or operand position, and the second for
1067 appearances of the variable on the left-hand-side of an assignment.
1069 For example, the previous @code{bar-alias} example could be expressed
1070 more succinctly like this:
1073 (define-syntax bar-alias
1076 ((set! var val) (set! bar val))))
1080 As before, the templates in @code{identifier-syntax} forms do not need
1081 wrapping in @code{#'} syntax forms.
1085 @node Syntax Parameters
1086 @subsection Syntax Parameters
1088 Syntax parameters@footnote{Described in the paper @cite{Keeping it Clean
1089 with Syntax Parameters} by Barzilay, Culpepper and Flatt.} are a
1090 mechanism for rebinding a macro definition within the dynamic extent of
1091 a macro expansion. This provides a convenient solution to one of the
1092 most common types of unhygienic macro: those that introduce a unhygienic
1093 binding each time the macro is used. Examples include a @code{lambda}
1094 form with a @code{return} keyword, or class macros that introduce a
1095 special @code{self} binding.
1097 With syntax parameters, instead of introducing the binding
1098 unhygienically each time, we instead create one binding for the keyword,
1099 which we can then adjust later when we want the keyword to have a
1100 different meaning. As no new bindings are introduced, hygiene is
1101 preserved. This is similar to the dynamic binding mechanisms we have at
1102 run-time (@pxref{SRFI-39, parameters}), except that the dynamic binding
1103 only occurs during macro expansion. The code after macro expansion
1104 remains lexically scoped.
1106 @deffn {Syntax} define-syntax-parameter keyword transformer
1107 Binds @var{keyword} to the value obtained by evaluating
1108 @var{transformer}. The @var{transformer} provides the default expansion
1109 for the syntax parameter, and in the absence of
1110 @code{syntax-parameterize}, is functionally equivalent to
1111 @code{define-syntax}. Usually, you will just want to have the
1112 @var{transformer} throw a syntax error indicating that the @var{keyword}
1113 is supposed to be used in conjunction with another macro, for example:
1115 (define-syntax-parameter return
1117 (syntax-violation 'return "return used outside of a lambda^" stx)))
1121 @deffn {Syntax} syntax-parameterize ((keyword transformer) @dots{}) exp @dots{}
1122 Adjusts @var{keyword} @dots{} to use the values obtained by evaluating
1123 their @var{transformer} @dots{}, in the expansion of the @var{exp}
1124 @dots{} forms. Each @var{keyword} must be bound to a syntax-parameter.
1125 @code{syntax-parameterize} differs from @code{let-syntax}, in that the
1126 binding is not shadowed, but adjusted, and so uses of the keyword in the
1127 expansion of @var{exp} @dots{} use the new transformers. This is
1128 somewhat similar to how @code{parameterize} adjusts the values of
1129 regular parameters, rather than creating new bindings.
1132 (define-syntax lambda^
1134 [(lambda^ argument-list body body* ...)
1135 (lambda argument-list
1136 (call-with-current-continuation
1138 ;; In the body we adjust the 'return' keyword so that calls
1139 ;; to 'return' are replaced with calls to the escape
1141 (syntax-parameterize ([return (syntax-rules ()
1142 [(return vals (... ...))
1143 (escape vals (... ...))])])
1144 body body* ...))))]))
1146 ;; Now we can write functions that return early. Here, 'product' will
1147 ;; return immediately if it sees any 0 element.
1161 @subsection Eval-when
1163 As @code{syntax-case} macros have the whole power of Scheme available to them,
1164 they present a problem regarding time: when a macro runs, what parts of the
1165 program are available for the macro to use?
1167 The default answer to this question is that when you import a module (via
1168 @code{define-module} or @code{use-modules}), that module will be loaded up at
1169 expansion-time, as well as at run-time. Additionally, top-level syntactic
1170 definitions within one compilation unit made by @code{define-syntax} are also
1171 evaluated at expansion time, in the order that they appear in the compilation
1174 But if a syntactic definition needs to call out to a normal procedure at
1175 expansion-time, it might well need need special declarations to indicate that
1176 the procedure should be made available at expansion-time.
1178 For example, the following code will work at a REPL, but not in a file:
1182 (use-modules (srfi srfi-19))
1183 (define (date) (date->string (current-date)))
1184 (define-syntax %date (identifier-syntax (date)))
1185 (define *compilation-date* %date)
1188 It works at a REPL because the expressions are evaluated one-by-one, in order,
1189 but if placed in a file, the expressions are expanded one-by-one, but not
1190 evaluated until the compiled file is loaded.
1192 The fix is to use @code{eval-when}.
1195 ;; correct: using eval-when
1196 (use-modules (srfi srfi-19))
1197 (eval-when (expand load eval)
1198 (define (date) (date->string (current-date))))
1199 (define-syntax %date (identifier-syntax (date)))
1200 (define *compilation-date* %date)
1203 @deffn {Syntax} eval-when conditions exp...
1204 Evaluate @var{exp...} under the given @var{conditions}. Valid
1209 Evaluate during macro expansion, whether compiling or not.
1212 Evaluate during the evaluation phase of compiled code, e.g. when loading
1213 a compiled module or running compiled code at the REPL.
1216 Evaluate during the evaluation phase of non-compiled code.
1219 Evaluate during macro expansion, but only when compiling.
1222 In other words, when using the primitive evaluator, @code{eval-when}
1223 expressions with @code{expand} are run during macro expansion, and those
1224 with @code{eval} are run during the evaluation phase.
1226 When using the compiler, @code{eval-when} expressions with either
1227 @code{expand} or @code{compile} are run during macro expansion, and
1228 those with @code{load} are run during the evaluation phase.
1230 When in doubt, use the three conditions @code{(expand load eval)}, as in
1231 the example above. Other uses of @code{eval-when} may void your
1232 warranty or poison your cat.
1235 @node Macro Expansion
1236 @subsection Macro Expansion
1238 Usually, macros are expanded on behalf of the user as needed. Macro
1239 expansion is an integral part of @code{eval} and @code{compile}. Users
1240 can also expand macros at the REPL prompt via the @code{expand} REPL
1241 command; @xref{Compile Commands}.
1243 Macros can also be expanded programmatically, via @code{macroexpand},
1244 but the details get a bit hairy for two reasons.
1246 The first complication is that the result of macro-expansion isn't
1247 Scheme: it's Tree-IL, Guile's high-level intermediate language.
1248 @xref{Tree-IL}. As ``hygienic macros'' can produce identifiers that are
1249 distinct but have the same name, the output format needs to be able to
1250 represent distinctions between variable identities and names. Again,
1251 @xref{Tree-IL}, for all the details. The easiest thing is to just run
1252 @code{tree-il->scheme} on the result of macro-expansion:
1255 (macroexpand '(+ 1 2))
1257 #<tree-il (call (toplevel +) (const 1) (const 2))>
1259 (use-modules (language tree-il))
1260 (tree-il->scheme (macroexpand '(+ 1 2)))
1265 The second complication involves @code{eval-when}. As an example, what
1266 would it mean to macro-expand the definition of a macro?
1269 (macroexpand '(define-syntax qux (identifier-syntax 'bar)))
1274 The answer is that it depends who is macro-expanding, and why. Do you
1275 define the macro in the current environment? Residualize a macro
1276 definition? Both? Neither? The default is to expand in ``eval'' mode,
1277 which means an @code{eval-when} clauses will only proceed when
1278 @code{eval} (or @code{expand}) is in its condition set. Top-level
1279 macros will be @code{eval}'d in the top-level environment.
1281 In this way @code{(macroexpand @var{foo})} is equivalent to
1282 @code{(macroexpand @var{foo} 'e '(eval))}. The second argument is the
1283 mode (@code{'e} for ``eval'') and the second is the
1284 eval-syntax-expanders-when parameter (only @code{eval} in this default
1287 But if you are compiling the macro definition, probably you want to
1288 reify the macro definition itself. In that case you pass @code{'c} as
1289 the second argument to @code{macroexpand}. But probably you want the
1290 macro definition to be present at compile time as well, so you pass
1291 @code{'(compile load eval)} as the @var{esew} parameter. In fact
1292 @code{(compile @var{foo} #:to 'tree-il)} is entirely equivalent to
1293 @code{(macroexpand @var{foo} 'c '(compile load eval))}; @xref{The Scheme
1296 It's a terrible interface; we know. The macroexpander is somewhat
1297 tricksy regarding modes, so unless you are building a macro-expanding
1298 tool, we suggest to avoid invoking it directly.
1301 @node Hygiene and the Top-Level
1302 @subsection Hygiene and the Top-Level
1304 Consider the following macro.
1307 (define-syntax-rule (defconst name val)
1310 (define-syntax-rule (name) t)))
1313 If we use it to make a couple of bindings:
1320 The expansion would look something like this:
1325 (define-syntax-rule (foo) t))
1328 (define-syntax-rule (bar) t))
1331 As the two @code{t} bindings were introduced by the macro, they should
1332 be introduced hygienically -- and indeed they are, inside a lexical
1333 contour (a @code{let} or some other lexical scope). The @code{t}
1334 reference in @code{foo} is distinct to the reference in @code{bar}.
1336 At the top-level things are more complicated. Before Guile 2.2, a use
1337 of @code{defconst} at the top-level would not introduce a fresh binding
1338 for @code{t}. This was consistent with a weaselly interpretation of the
1339 Scheme standard, in which all possible bindings may be assumed to exist,
1340 at the top-level, and in which we merely take advantage of toplevel
1341 @code{define} of an existing binding being equivalent to @code{set!}.
1342 But it's not a good reason.
1344 The solution is to create fresh names for all bindings introduced by
1345 macros -- not just bindings in lexical contours, but also bindings
1346 introduced at the top-level.
1348 However, the obvious strategy of just giving random names to introduced
1349 toplevel identifiers poses a problem for separate compilation. Consider
1350 without loss of generality a @code{defconst} of @code{foo} in module
1351 @code{a} that introduces the fresh top-level name @code{t-1}. If we
1352 then compile a module @code{b} that uses @code{foo}, there is now a
1353 reference to @code{t-1} in module @code{b}. If module @code{a} is then
1354 expanded again, for whatever reason, for example in a simple
1355 recompilation, the introduced @code{t} gets a fresh name; say,
1356 @code{t-2}. Now module @code{b} has broken because module @code{a} no
1357 longer has a binding for @code{t-1}.
1359 If introduced top-level identifiers ``escape'' a module, in whatever
1360 way, they then form part of the binary interface (ABI) of a module. It
1361 is unacceptable from an engineering point of view to allow the ABI to
1362 change randomly. (It also poses practical problems in meeting the
1363 recompilation conditions of the Lesser GPL license, for such modules.)
1364 For this reason many people prefer to never use identifier-introducing
1365 macros at the top-level, instead making those macros receive the names
1366 for their introduced identifiers as part of their arguments, or to
1367 construct them programmatically and use @code{datum->syntax}. But this
1368 approach requires omniscience as to the implementation of all macros one
1369 might use, and also limits the expressive power of Scheme macros.
1371 There is no perfect solution to this issue. Guile does a terrible thing
1372 here. When it goes to introduce a top-level identifier, Guile gives the
1373 identifier a pseudo-fresh name: a name that depends on the hash of the
1374 source expression in which the name occurs. The result in this case is
1375 that the introduced definitions expand as:
1379 (define t-1dc5e42de7c1050c 42)
1380 (define-syntax-rule (foo) t-1dc5e42de7c1050c))
1382 (define t-10cb8ce9fdddd6e9 37)
1383 (define-syntax-rule (bar) t-10cb8ce9fdddd6e9))
1386 However, note that as the hash depends solely on the expression
1387 introducing the definition, we also have:
1392 (define t-1dc5e42de7c1050c 42)
1393 (define-syntax-rule (baz) t-1dc5e42de7c1050c))
1396 Note that the introduced binding has the same name! This is because the
1397 source expression, @code{(define t 42)}, was the same. Probably you
1398 will never see an error in this area, but it is important to understand
1399 the components of the interface of a module, and that interface may
1400 include macro-introduced identifiers.
1403 @node Internal Macros
1404 @subsection Internal Macros
1406 @deffn {Scheme Procedure} make-syntax-transformer name type binding
1407 Construct a syntax transformer object. This is part of Guile's low-level support
1411 @deffn {Scheme Procedure} macro? obj
1412 @deffnx {C Function} scm_macro_p (obj)
1413 Return @code{#t} if @var{obj} is a syntax transformer, or @code{#f}
1416 Note that it's a bit difficult to actually get a macro as a first-class object;
1417 simply naming it (like @code{case}) will produce a syntax error. But it is
1418 possible to get these objects using @code{module-ref}:
1421 (macro? (module-ref (current-module) 'case))
1426 @deffn {Scheme Procedure} macro-type m
1427 @deffnx {C Function} scm_macro_type (m)
1428 Return the @var{type} that was given when @var{m} was constructed, via
1429 @code{make-syntax-transformer}.
1432 @deffn {Scheme Procedure} macro-name m
1433 @deffnx {C Function} scm_macro_name (m)
1434 Return the name of the macro @var{m}.
1437 @deffn {Scheme Procedure} macro-binding m
1438 @deffnx {C Function} scm_macro_binding (m)
1439 Return the binding of the macro @var{m}.
1442 @deffn {Scheme Procedure} macro-transformer m
1443 @deffnx {C Function} scm_macro_transformer (m)
1444 Return the transformer of the macro @var{m}. This will return a procedure, for
1445 which one may ask the docstring. That's the whole reason this section is
1446 documented. Actually a part of the result of @code{macro-binding}.
1451 @c TeX-master: "guile.texi"