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 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 Macro expansion is a separate phase of evaluation, run before code is
28 interpreted or compiled. A macro is a program that runs on programs, translating
29 an embedded language into core Scheme.
32 * Defining Macros:: Binding macros, globally and locally.
33 * Syntax Rules:: Pattern-driven macros.
34 * Syntax Case:: Procedural, hygienic macros.
35 * Defmacros:: Lisp-style macros.
36 * Identifier Macros:: Identifier macros.
37 * Eval When:: Affecting the expand-time environment.
38 * Internal Macros:: Macros as first-class values.
42 @subsection Defining Macros
44 A macro is a binding between a keyword and a syntax transformer. Since it's
45 difficult to discuss @code{define-syntax} without discussing the format of
46 transformers, consider the following example macro definition:
51 ((when condition exp ...)
57 (display "let's go\n"))
62 In this example, the @code{when} binding is bound with @code{define-syntax}.
63 Syntax transformers are discussed in more depth in @ref{Syntax Rules} and
66 @deffn {Syntax} define-syntax keyword transformer
67 Bind @var{keyword} to the syntax transformer obtained by evaluating
70 After a macro has been defined, further instances of @var{keyword} in Scheme
71 source code will invoke the syntax transformer defined by @var{transformer}.
74 One can also establish local syntactic bindings with @code{let-syntax}.
76 @deffn {Syntax} let-syntax ((keyword transformer) ...) exp...
77 Bind @var{keyword...} to @var{transformer...} while expanding @var{exp...}.
79 A @code{let-syntax} binding only exists at expansion-time.
84 ((unless condition exp ...)
90 @result{} "rock rock rock"
94 A @code{define-syntax} form is valid anywhere a definition may appear: at the
95 top-level, or locally. Just as a local @code{define} expands out to an instance
96 of @code{letrec}, a local @code{define-syntax} expands out to
99 @deffn {Syntax} letrec-syntax ((keyword transformer) ...) exp...
100 Bind @var{keyword...} to @var{transformer...} while expanding @var{exp...}.
102 In the spirit of @code{letrec} versus @code{let}, an expansion produced by
103 @var{transformer} may reference a @var{keyword} bound by the
104 same @var{letrec-syntax}.
107 (letrec-syntax ((my-or
113 ((my-or exp rest ...)
117 (my-or rest ...)))))))
118 (my-or #f "rockaway beach"))
119 @result{} "rockaway beach"
124 @subsection Syntax-rules Macros
126 @code{syntax-rules} macros are simple, pattern-driven syntax transformers, with
127 a beauty worthy of Scheme.
129 @deffn {Syntax} syntax-rules literals (pattern template)...
130 Create a syntax transformer that will rewrite an expression using the rules
131 embodied in the @var{pattern} and @var{template} clauses.
134 A @code{syntax-rules} macro consists of three parts: the literals (if any), the
135 patterns, and as many templates as there are patterns.
137 When the syntax expander sees the invocation of a @code{syntax-rules} macro, it
138 matches the expression against the patterns, in order, and rewrites the
139 expression using the template from the first matching pattern. If no pattern
140 matches, a syntax error is signalled.
142 @subsubsection Patterns
144 We have already seen some examples of patterns in the previous section:
145 @code{(unless condition exp ...)}, @code{(my-or exp)}, and so on. A pattern is
146 structured like the expression that it is to match. It can have nested structure
147 as well, like @code{(let ((var val) ...) exp exp* ...)}. Broadly speaking,
148 patterns are made of lists, improper lists, vectors, identifiers, and datums.
149 Users can match a sequence of patterns using the ellipsis (@code{...}).
151 Identifiers in a pattern are called @dfn{literals} if they are present in the
152 @code{syntax-rules} literals list, and @dfn{pattern variables} otherwise. When
153 building up the macro output, the expander replaces instances of a pattern
154 variable in the template with the matched subexpression.
162 @result{} (foo . bar)
165 An improper list of patterns matches as rest arguments do:
170 ((_ (var val) . exps)
171 (let ((var val)) . exps))))
174 However this definition of @code{let1} probably isn't what you want, as the tail
175 pattern @var{exps} will match non-lists, like @code{(let1 (foo 'bar) . baz)}. So
176 often instead of using improper lists as patterns, ellipsized patterns are
177 better. Instances of a pattern variable in the template must be followed by an
183 ((_ (var val) exp ...)
184 (let ((var val)) exp ...))))
187 This @code{let1} probably still doesn't do what we want, because the body
188 matches sequences of zero expressions, like @code{(let1 (foo 'bar))}. In this
189 case we need to assert we have at least one body expression. A common idiom for
190 this is to name the ellipsized pattern variable with an asterisk:
195 ((_ (var val) exp exp* ...)
196 (let ((var val)) exp exp* ...))))
199 A vector of patterns matches a vector whose contents match the patterns,
200 including ellipsizing and tail patterns.
205 ((_ #((var val) ...) exp exp* ...)
206 (let ((var val) ...) exp exp* ...))))
207 (letv #((foo 'bar)) foo)
211 Literals are used to match specific datums in an expression, like the use of
212 @code{=>} and @code{else} in @code{cond} expressions.
216 (syntax-rules (=> else)
219 (if exp (fun exp) #f)))
220 ((cond1 test exp exp* ...)
221 (if test (begin exp exp* ...)))
222 ((cond1 else exp exp* ...)
223 (begin exp exp* ...))))
225 (define (square x) (* x x))
229 (cond1 10 => square))
230 @result{} #<procedure square (x)>
233 A literal matches an input expression if the input expression is an identifier
234 with the same name as the literal, and both are unbound@footnote{Language
235 lawyers probably see the need here for use of @code{literal-identifier=?} rather
236 than @code{free-identifier=?}, and would probably be correct. Patches
239 If a pattern is not a list, vector, or an identifier, it matches as a literal,
243 (define-syntax define-matcher-macro
251 (define-matcher-macro is-literal-foo? "foo")
253 (is-literal-foo? "foo")
255 (is-literal-foo? "bar")
258 (is-literal-foo? foo))
262 The last example indicates that matching happens at expansion-time, not
265 Syntax-rules macros are always used as @code{(@var{macro} . @var{args})}, and
266 the @var{macro} will always be a symbol. Correspondingly, a @code{syntax-rules}
267 pattern must be a list (proper or improper), and the first pattern in that list
268 must be an identifier. Incidentally it can be any identifier -- it doesn't have
269 to actually be the name of the macro. Thus the following three are equivalent:
275 (if c (begin e ...)))))
280 (if c (begin e ...)))))
284 ((something-else-entirely c e ...)
285 (if c (begin e ...)))))
288 For clarity, use one of the first two variants. Also note that since the pattern
289 variable will always match the macro itself (e.g., @code{cond1}), it is actually
290 left unbound in the template.
292 @subsubsection Hygiene
294 @code{syntax-rules} macros have a magical property: they preserve referential
295 transparency. When you read a macro definition, any free bindings in that macro
296 are resolved relative to the macro definition; and when you read a macro
297 instantiation, all free bindings in that expression are resolved relative to the
300 This property is sometimes known as @dfn{hygiene}, and it does aid in code
301 cleanliness. In your macro definitions, you can feel free to introduce temporary
302 variables, without worrying about inadvertently introducing bindings into the
305 Consider the definition of @code{my-or} from the previous section:
314 ((my-or exp rest ...)
318 (my-or rest ...))))))
321 A naive expansion of @code{(let ((t #t)) (my-or #f t))} would yield:
331 Which clearly is not what we want. Somehow the @code{t} in the definition is
332 distinct from the @code{t} at the site of use; and it is indeed this distinction
333 that is maintained by the syntax expander, when expanding hygienic macros.
335 This discussion is mostly relevant in the context of traditional Lisp macros
336 (@pxref{Defmacros}), which do not preserve referential transparency. Hygiene
337 adds to the expressive power of Scheme.
339 @subsubsection Shorthands
341 One often ends up writing simple one-clause @code{syntax-rules} macros.
342 There is a convenient shorthand for this idiom, in the form of
343 @code{define-syntax-rule}.
345 @deffn {Syntax} define-syntax-rule (keyword . pattern) [docstring] template
346 Define @var{keyword} as a new @code{syntax-rules} macro with one clause.
349 Cast into this form, our @code{when} example is significantly shorter:
352 (define-syntax-rule (when c e ...)
353 (if c (begin e ...)))
356 @subsubsection Further Information
358 For a formal definition of @code{syntax-rules} and its pattern language, see
359 @xref{Macros, , Macros, r5rs, Revised(5) Report on the Algorithmic Language
362 @code{syntax-rules} macros are simple and clean, but do they have limitations.
363 They do not lend themselves to expressive error messages: patterns either match
364 or they don't. Their ability to generate code is limited to template-driven
365 expansion; often one needs to define a number of helper macros to get real work
366 done. Sometimes one wants to introduce a binding into the lexical context of the
367 generated code; this is impossible with @code{syntax-rules}. Relatedly, they
368 cannot programmatically generate identifiers.
370 The solution to all of these problems is to use @code{syntax-case} if you need
371 its features. But if for some reason you're stuck with @code{syntax-rules}, you
372 might enjoy Joe Marshall's
373 @uref{http://sites.google.com/site/evalapply/eccentric.txt,@code{syntax-rules}
374 Primer for the Merely Eccentric}.
377 @subsection Support for the @code{syntax-case} System
379 @code{syntax-case} macros are procedural syntax transformers, with a power
382 @deffn {Syntax} syntax-case syntax literals (pattern [guard] exp)...
383 Match the syntax object @var{syntax} against the given patterns, in order. If a
384 @var{pattern} matches, return the result of evaluating the associated @var{exp}.
387 Compare the following definitions of @code{when}:
393 (if test (begin e e* ...)))))
399 #'(if test (begin e e* ...))))))
402 Clearly, the @code{syntax-case} definition is similar to its @code{syntax-rules}
403 counterpart, and equally clearly there are some differences. The
404 @code{syntax-case} definition is wrapped in a @code{lambda}, a function of one
405 argument; that argument is passed to the @code{syntax-case} invocation; and the
406 ``return value'' of the macro has a @code{#'} prefix.
408 All of these differences stem from the fact that @code{syntax-case} does not
409 define a syntax transformer itself -- instead, @code{syntax-case} expressions
410 provide a way to destructure a @dfn{syntax object}, and to rebuild syntax
413 So the @code{lambda} wrapper is simply a leaky implementation detail, that
414 syntax transformers are just functions that transform syntax to syntax. This
415 should not be surprising, given that we have already described macros as
416 ``programs that write programs''. @code{syntax-case} is simply a way to take
417 apart and put together program text, and to be a valid syntax transformer it
418 needs to be wrapped in a procedure.
420 Unlike traditional Lisp macros (@pxref{Defmacros}), @code{syntax-case} macros
421 transform syntax objects, not raw Scheme forms. Recall the naive expansion of
422 @code{my-or} given in the previous section:
433 Raw Scheme forms simply don't have enough information to distinguish the first
434 two @code{t} instances in @code{(if t t t)} from the third @code{t}. So instead
435 of representing identifiers as symbols, the syntax expander represents
436 identifiers as annotated syntax objects, attaching such information to those
437 syntax objects as is needed to maintain referential transparency.
439 @deffn {Syntax} syntax form
440 Create a syntax object wrapping @var{form} within the current lexical context.
443 Syntax objects are typically created internally to the process of expansion, but
444 it is possible to create them outside of syntax expansion:
447 (syntax (foo bar baz))
448 @result{} #<some representation of that syntax>
452 However it is more common, and useful, to create syntax objects when building
453 output from a @code{syntax-case} expression.
460 (syntax (+ exp 1))))))
463 It is not strictly necessary for a @code{syntax-case} expression to return a
464 syntax object, because @code{syntax-case} expressions can be used in helper
465 functions, or otherwise used outside of syntax expansion itself. However a
466 syntax transformer procedure must return a syntax object, so most uses of
467 @code{syntax-case} do end up returning syntax objects.
469 Here in this case, the form that built the return value was @code{(syntax (+ exp
470 1))}. The interesting thing about this is that within a @code{syntax}
471 expression, any appearance of a pattern variable is substituted into the
472 resulting syntax object, carrying with it all relevant metadata from the source
473 expression, such as lexical identity and source location.
475 Indeed, a pattern variable may only be referenced from inside a @code{syntax}
476 form. The syntax expander would raise an error when defining @code{add1} if it
477 found @var{exp} referenced outside a @code{syntax} form.
479 Since @code{syntax} appears frequently in macro-heavy code, it has a special
480 reader macro: @code{#'}. @code{#'foo} is transformed by the reader into
481 @code{(syntax foo)}, just as @code{'foo} is transformed into @code{(quote foo)}.
483 The pattern language used by @code{syntax-case} is conveniently the same
484 language used by @code{syntax-rules}. Given this, Guile actually defines
485 @code{syntax-rules} in terms of @code{syntax-case}:
488 (define-syntax syntax-rules
491 ((_ (k ...) ((keyword . pattern) template) ...)
493 (syntax-case x (k ...)
494 ((dummy . pattern) #'template)
500 @subsubsection Why @code{syntax-case}?
502 The examples we have shown thus far could just as well have been expressed with
503 @code{syntax-rules}, and have just shown that @code{syntax-case} is more
504 verbose, which is true. But there is a difference: @code{syntax-case} creates
505 @emph{procedural} macros, giving the full power of Scheme to the macro expander.
506 This has many practical applications.
508 A common desire is to be able to match a form only if it is an identifier. This
509 is impossible with @code{syntax-rules}, given the datum matching forms. But with
510 @code{syntax-case} it is easy:
512 @deffn {Scheme Procedure} identifier? syntax-object
513 Returns @code{#t} iff @var{syntax-object} is an identifier.
517 ;; relying on previous add1 definition
521 ((_ var) (identifier? #'var)
522 #'(set! var (add1 var))))))
527 (add1! "not-an-identifier") @result{} error
530 With @code{syntax-rules}, the error for @code{(add1! "not-an-identifier")} would
531 be something like ``invalid @code{set!}''. With @code{syntax-case}, it will say
532 something like ``invalid @code{add1!}'', because we attach the @dfn{guard
533 clause} to the pattern: @code{(identifier? #'var)}. This becomes more important
534 with more complicated macros. It is necessary to use @code{identifier?}, because
535 to the expander, an identifier is more than a bare symbol.
537 Note that even in the guard clause, we reference the @var{var} pattern variable
538 within a @code{syntax} form, via @code{#'var}.
540 Another common desire is to introduce bindings into the lexical context of the
541 output expression. One example would be in the so-called ``anaphoric macros'',
542 like @code{aif}. Anaphoric macros bind some expression to a well-known
543 identifier, often @code{it}, within their bodies. For example, in @code{(aif
544 (foo) (bar it))}, @code{it} would be bound to the result of @code{(foo)}.
546 To begin with, we should mention a solution that doesn't work:
555 (if it then else))))))
558 The reason that this doesn't work is that, by default, the expander will
559 preserve referential transparency; the @var{then} and @var{else} expressions
560 won't have access to the binding of @code{it}.
562 But they can, if we explicitly introduce a binding via @code{datum->syntax}.
564 @deffn {Scheme Procedure} datum->syntax for-syntax datum
565 Create a syntax object that wraps @var{datum}, within the lexical context
566 corresponding to the syntax object @var{for-syntax}.
569 For completeness, we should mention that it is possible to strip the metadata
570 from a syntax object, returning a raw Scheme datum:
572 @deffn {Scheme Procedure} syntax->datum syntax-object
573 Strip the metadata from @var{syntax-object}, returning its contents as a raw
577 In this case we want to introduce @code{it} in the context of the whole
578 expression, so we can create a syntax object as @code{(datum->syntax x 'it)},
579 where @code{x} is the whole expression, as passed to the transformer procedure.
581 Here's another solution that doesn't work:
584 ;; doesn't work either
589 (let ((it (datum->syntax x 'it)))
591 (if it then else)))))))
594 The reason that this one doesn't work is that there are really two
595 environments at work here -- the environment of pattern variables, as
596 bound by @code{syntax-case}, and the environment of lexical variables,
597 as bound by normal Scheme. The outer let form establishes a binding in
598 the environment of lexical variables, but the inner let form is inside a
599 syntax form, where only pattern variables will be substituted. Here we
600 need to introduce a piece of the lexical environment into the pattern
601 variable environment, and we can do so using @code{syntax-case} itself:
604 ;; works, but is obtuse
609 ;; invoking syntax-case on the generated
610 ;; syntax object to expose it to `syntax'
611 (syntax-case (datum->syntax x 'it) ()
614 (if it then else))))))))
616 (aif (getuid) (display it) (display "none")) (newline)
620 However there are easier ways to write this. @code{with-syntax} is often
623 @deffn {Syntax} with-syntax ((pat val)...) exp...
624 Bind patterns @var{pat} from their corresponding values @var{val}, within the
625 lexical context of @var{exp...}.
633 (with-syntax ((it (datum->syntax x 'it)))
635 (if it then else)))))))
639 As you might imagine, @code{with-syntax} is defined in terms of
640 @code{syntax-case}. But even that might be off-putting to you if you are an old
641 Lisp macro hacker, used to building macro output with @code{quasiquote}. The
642 issue is that @code{with-syntax} creates a separation between the point of
643 definition of a value and its point of substitution.
647 @pindex unsyntax-splicing
648 So for cases in which a @code{quasiquote} style makes more sense,
649 @code{syntax-case} also defines @code{quasisyntax}, and the related
650 @code{unsyntax} and @code{unsyntax-splicing}, abbreviated by the reader as
651 @code{#`}, @code{#,}, and @code{#,@@}, respectively.
653 For example, to define a macro that inserts a compile-time timestamp into a
654 source file, one may write:
657 (define-syntax display-compile-timestamp
662 (display "The compile timestamp was: ")
663 (display #,(current-time))
667 Finally, we should mention the following helper procedures defined by the core
668 of @code{syntax-case}:
670 @deffn {Scheme Procedure} bound-identifier=? a b
671 Returns @code{#t} iff the syntax objects @var{a} and @var{b} refer to the same
672 lexically-bound identifier.
675 @deffn {Scheme Procedure} free-identifier=? a b
676 Returns @code{#t} iff the syntax objects @var{a} and @var{b} refer to the same
680 @deffn {Scheme Procedure} generate-temporaries ls
681 Return a list of temporary identifiers as long as @var{ls} is long.
684 Readers interested in further information on @code{syntax-case} macros should
685 see R. Kent Dybvig's excellent @cite{The Scheme Programming Language}, either
686 edition 3 or 4, in the chapter on syntax. Dybvig was the primary author of the
687 @code{syntax-case} system. The book itself is available online at
688 @uref{http://scheme.com/tspl4/}.
691 @subsection Lisp-style Macro Definitions
693 The traditional way to define macros in Lisp is very similar to procedure
694 definitions. The key differences are that the macro definition body should
695 return a list that describes the transformed expression, and that the definition
696 is marked as a macro definition (rather than a procedure definition) by the use
697 of a different definition keyword: in Lisp, @code{defmacro} rather than
698 @code{defun}, and in Scheme, @code{define-macro} rather than @code{define}.
701 @fnindex define-macro
702 Guile supports this style of macro definition using both @code{defmacro}
703 and @code{define-macro}. The only difference between them is how the
704 macro name and arguments are grouped together in the definition:
707 (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
714 (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
718 The difference is analogous to the corresponding difference between
719 Lisp's @code{defun} and Scheme's @code{define}.
721 Having read the previous section on @code{syntax-case}, it's probably clear that
722 Guile actually implements defmacros in terms of @code{syntax-case}, applying the
723 transformer on the expression between invocations of @code{syntax->datum} and
724 @code{datum->syntax}. This realization leads us to the problem with defmacros,
725 that they do not preserve referential transparency. One can be careful to not
726 introduce bindings into expanded code, via liberal use of @code{gensym}, but
727 there is no getting around the lack of referential transparency for free
728 bindings in the macro itself.
730 Even a macro as simple as our @code{when} from before is difficult to get right:
733 (define-macro (when cond exp . rest)
735 (begin ,exp . ,rest)))
737 (when #f (display "Launching missiles!\n"))
741 (when #f (display "Launching missiles!\n")))
742 @print{} Launching missiles!
743 @result{} (#f #<unspecified>)
746 Guile's perspective is that defmacros have had a good run, but that modern
747 macros should be written with @code{syntax-rules} or @code{syntax-case}. There
748 are still many uses of defmacros within Guile itself, but we will be phasing
749 them out over time. Of course we won't take away @code{defmacro} or
750 @code{define-macro} themselves, as there is lots of code out there that uses
754 @node Identifier Macros
755 @subsection Identifier Macros
757 When the syntax expander sees a form in which the first element is a macro, the
758 whole form gets passed to the macro's syntax transformer. One may visualize this
762 (define-syntax foo foo-transformer)
765 (foo-transformer #'(foo @var{arg}...))
768 If, on the other hand, a macro is referenced in some other part of a form, the
769 syntax transformer is invoked with only the macro reference, not the whole form.
772 (define-syntax foo foo-transformer)
775 (foo-transformer #'foo)
778 This allows bare identifier references to be replaced programmatically via a
779 macro. @code{syntax-rules} provides some syntax to effect this transformation
782 @deffn {Syntax} identifier-syntax exp
783 Returns a macro transformer that will replace occurrences of the macro with
787 For example, if you are importing external code written in terms of @code{fx+},
788 the fixnum addition operator, but Guile doesn't have @code{fx+}, you may use the
789 following to replace @code{fx+} with @code{+}:
792 (define-syntax fx+ (identifier-syntax +))
795 There is also special support for recognizing identifiers on the
796 left-hand side of a @code{set!} expression, as in the following:
799 (define-syntax foo foo-transformer)
802 (foo-transformer #'(set! foo @var{val}))
803 ;; iff foo-transformer is a "variable transformer"
806 As the example notes, the transformer procedure must be explicitly
807 marked as being a ``variable transformer'', as most macros aren't
808 written to discriminate on the form in the operator position.
810 @deffn {Scheme Procedure} make-variable-transformer transformer
811 Mark the @var{transformer} procedure as being a ``variable
812 transformer''. In practice this means that, when bound to a syntactic
813 keyword, it may detect references to that keyword on the left-hand-side
818 (define-syntax bar-alias
819 (make-variable-transformer
821 (syntax-case x (set!)
822 ((set! var val) #'(set! bar val))
823 ((var arg ...) #'(bar arg ...))
824 (var (identifier? #'var) #'bar)))))
826 bar-alias @result{} 10
830 bar-alias @result{} 30
834 There is an extension to identifier-syntax which allows it to handle the
835 @code{set!} case as well:
837 @deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2)
838 Create a variable transformer. The first clause is used for references
839 to the variable in operator or operand position, and the second for
840 appearances of the variable on the left-hand-side of an assignment.
842 For example, the previous @code{bar-alias} example could be expressed
843 more succinctly like this:
846 (define-syntax bar-alias
849 ((set! var val) (set! bar val))))
853 As before, the templates in @code{identifier-syntax} forms do not need
854 wrapping in @code{#'} syntax forms.
859 @subsection Eval-when
861 As @code{syntax-case} macros have the whole power of Scheme available to them,
862 they present a problem regarding time: when a macro runs, what parts of the
863 program are available for the macro to use?
865 The default answer to this question is that when you import a module (via
866 @code{define-module} or @code{use-modules}), that module will be loaded up at
867 expansion-time, as well as at run-time. Additionally, top-level syntactic
868 definitions within one compilation unit made by @code{define-syntax} are also
869 evaluated at expansion time, in the order that they appear in the compilation
872 But if a syntactic definition needs to call out to a normal procedure at
873 expansion-time, it might well need need special declarations to indicate that
874 the procedure should be made available at expansion-time.
876 For example, the following code will work at a REPL, but not in a file:
880 (use-modules (srfi srfi-19))
881 (define (date) (date->string (current-date)))
882 (define-syntax %date (identifier-syntax (date)))
883 (define *compilation-date* %date)
886 It works at a REPL because the expressions are evaluated one-by-one, in order,
887 but if placed in a file, the expressions are expanded one-by-one, but not
888 evaluated until the compiled file is loaded.
890 The fix is to use @code{eval-when}.
893 ;; correct: using eval-when
894 (use-modules (srfi srfi-19))
895 (eval-when (compile load eval)
896 (define (date) (date->string (current-date))))
897 (define-syntax %date (identifier-syntax (date)))
898 (define *compilation-date* %date)
901 @deffn {Syntax} eval-when conditions exp...
902 Evaluate @var{exp...} under the given @var{conditions}. Valid conditions include
903 @code{eval}, @code{load}, and @code{compile}. If you need to use
904 @code{eval-when}, use it with all three conditions, as in the above example.
905 Other uses of @code{eval-when} may void your warranty or poison your cat.
908 @node Internal Macros
909 @subsection Internal Macros
911 @deffn {Scheme Procedure} make-syntax-transformer name type binding
912 Construct a syntax transformer object. This is part of Guile's low-level support
916 @deffn {Scheme Procedure} macro? obj
917 @deffnx {C Function} scm_macro_p (obj)
918 Return @code{#t} iff @var{obj} is a syntax transformer.
920 Note that it's a bit difficult to actually get a macro as a first-class object;
921 simply naming it (like @code{case}) will produce a syntax error. But it is
922 possible to get these objects using @code{module-ref}:
925 (macro? (module-ref (current-module) 'case))
930 @deffn {Scheme Procedure} macro-type m
931 @deffnx {C Function} scm_macro_type (m)
932 Return the @var{type} that was given when @var{m} was constructed, via
933 @code{make-syntax-transformer}.
936 @deffn {Scheme Procedure} macro-name m
937 @deffnx {C Function} scm_macro_name (m)
938 Return the name of the macro @var{m}.
941 @deffn {Scheme Procedure} macro-binding m
942 @deffnx {C Function} scm_macro_binding (m)
943 Return the binding of the macro @var{m}.
946 @deffn {Scheme Procedure} macro-transformer m
947 @deffnx {C Function} scm_macro_transformer (m)
948 Return the transformer of the macro @var{m}. This will return a procedure, for
949 which one may ask the docstring. That's the whole reason this section is
950 documented. Actually a part of the result of @code{macro-binding}.
955 @c TeX-master: "guile.texi"