2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
11 At its best, programming in Lisp is an iterative process of building up a
12 language appropriate to the problem at hand, and then solving the problem in
13 that language. Defining new procedures is part of that, but Lisp also allows
14 the user to extend its syntax, with its famous @dfn{macros}.
17 @cindex transformation
18 Macros are syntactic extensions which cause the expression that they appear in
19 to be transformed in some way @emph{before} being evaluated. In expressions that
20 are intended for macro transformation, the identifier that names the relevant
21 macro must appear as the first element, like this:
24 (@var{macro-name} @var{macro-args} @dots{})
27 @cindex macro expansion
28 Macro expansion is a separate phase of evaluation, run before code is
29 interpreted or compiled. A macro is a program that runs on programs, translating
30 an embedded language into core Scheme.
33 * Defining Macros:: Binding macros, globally and locally.
34 * Syntax Rules:: Pattern-driven macros.
35 * Syntax Case:: Procedural, hygienic macros.
36 * Defmacros:: Lisp-style macros.
37 * Identifier Macros:: Identifier macros.
38 * Eval When:: Affecting the expand-time environment.
39 * Internal Macros:: Macros as first-class values.
43 @subsection Defining Macros
45 A macro is a binding between a keyword and a syntax transformer. Since it's
46 difficult to discuss @code{define-syntax} without discussing the format of
47 transformers, consider the following example macro definition:
52 ((when condition exp ...)
58 (display "let's go\n"))
63 In this example, the @code{when} binding is bound with @code{define-syntax}.
64 Syntax transformers are discussed in more depth in @ref{Syntax Rules} and
67 @deffn {Syntax} define-syntax keyword transformer
68 Bind @var{keyword} to the syntax transformer obtained by evaluating
71 After a macro has been defined, further instances of @var{keyword} in Scheme
72 source code will invoke the syntax transformer defined by @var{transformer}.
75 One can also establish local syntactic bindings with @code{let-syntax}.
77 @deffn {Syntax} let-syntax ((keyword transformer) ...) exp...
78 Bind @var{keyword...} to @var{transformer...} while expanding @var{exp...}.
80 A @code{let-syntax} binding only exists at expansion-time.
85 ((unless condition exp ...)
91 @result{} "rock rock rock"
95 A @code{define-syntax} form is valid anywhere a definition may appear: at the
96 top-level, or locally. Just as a local @code{define} expands out to an instance
97 of @code{letrec}, a local @code{define-syntax} expands out to
100 @deffn {Syntax} letrec-syntax ((keyword transformer) ...) exp...
101 Bind @var{keyword...} to @var{transformer...} while expanding @var{exp...}.
103 In the spirit of @code{letrec} versus @code{let}, an expansion produced by
104 @var{transformer} may reference a @var{keyword} bound by the
105 same @var{letrec-syntax}.
108 (letrec-syntax ((my-or
114 ((my-or exp rest ...)
118 (my-or rest ...)))))))
119 (my-or #f "rockaway beach"))
120 @result{} "rockaway beach"
125 @subsection Syntax-rules Macros
127 @code{syntax-rules} macros are simple, pattern-driven syntax transformers, with
128 a beauty worthy of Scheme.
130 @deffn {Syntax} syntax-rules literals (pattern template)...
131 Create a syntax transformer that will rewrite an expression using the rules
132 embodied in the @var{pattern} and @var{template} clauses.
135 A @code{syntax-rules} macro consists of three parts: the literals (if any), the
136 patterns, and as many templates as there are patterns.
138 When the syntax expander sees the invocation of a @code{syntax-rules} macro, it
139 matches the expression against the patterns, in order, and rewrites the
140 expression using the template from the first matching pattern. If no pattern
141 matches, a syntax error is signalled.
143 @subsubsection Patterns
145 We have already seen some examples of patterns in the previous section:
146 @code{(unless condition exp ...)}, @code{(my-or exp)}, and so on. A pattern is
147 structured like the expression that it is to match. It can have nested structure
148 as well, like @code{(let ((var val) ...) exp exp* ...)}. Broadly speaking,
149 patterns are made of lists, improper lists, vectors, identifiers, and datums.
150 Users can match a sequence of patterns using the ellipsis (@code{...}).
152 Identifiers in a pattern are called @dfn{literals} if they are present in the
153 @code{syntax-rules} literals list, and @dfn{pattern variables} otherwise. When
154 building up the macro output, the expander replaces instances of a pattern
155 variable in the template with the matched subexpression.
163 @result{} (foo . bar)
166 An improper list of patterns matches as rest arguments do:
171 ((_ (var val) . exps)
172 (let ((var val)) . exps))))
175 However this definition of @code{let1} probably isn't what you want, as the tail
176 pattern @var{exps} will match non-lists, like @code{(let1 (foo 'bar) . baz)}. So
177 often instead of using improper lists as patterns, ellipsized patterns are
178 better. Instances of a pattern variable in the template must be followed by an
184 ((_ (var val) exp ...)
185 (let ((var val)) exp ...))))
188 This @code{let1} probably still doesn't do what we want, because the body
189 matches sequences of zero expressions, like @code{(let1 (foo 'bar))}. In this
190 case we need to assert we have at least one body expression. A common idiom for
191 this is to name the ellipsized pattern variable with an asterisk:
196 ((_ (var val) exp exp* ...)
197 (let ((var val)) exp exp* ...))))
200 A vector of patterns matches a vector whose contents match the patterns,
201 including ellipsizing and tail patterns.
206 ((_ #((var val) ...) exp exp* ...)
207 (let ((var val) ...) exp exp* ...))))
208 (letv #((foo 'bar)) foo)
212 Literals are used to match specific datums in an expression, like the use of
213 @code{=>} and @code{else} in @code{cond} expressions.
217 (syntax-rules (=> else)
220 (if exp (fun exp) #f)))
221 ((cond1 test exp exp* ...)
222 (if test (begin exp exp* ...)))
223 ((cond1 else exp exp* ...)
224 (begin exp exp* ...))))
226 (define (square x) (* x x))
230 (cond1 10 => square))
231 @result{} #<procedure square (x)>
234 A literal matches an input expression if the input expression is an identifier
235 with the same name as the literal, and both are unbound@footnote{Language
236 lawyers probably see the need here for use of @code{literal-identifier=?} rather
237 than @code{free-identifier=?}, and would probably be correct. Patches
240 If a pattern is not a list, vector, or an identifier, it matches as a literal,
244 (define-syntax define-matcher-macro
252 (define-matcher-macro is-literal-foo? "foo")
254 (is-literal-foo? "foo")
256 (is-literal-foo? "bar")
259 (is-literal-foo? foo))
263 The last example indicates that matching happens at expansion-time, not
266 Syntax-rules macros are always used as @code{(@var{macro} . @var{args})}, and
267 the @var{macro} will always be a symbol. Correspondingly, a @code{syntax-rules}
268 pattern must be a list (proper or improper), and the first pattern in that list
269 must be an identifier. Incidentally it can be any identifier -- it doesn't have
270 to actually be the name of the macro. Thus the following three are equivalent:
276 (if c (begin e ...)))))
281 (if c (begin e ...)))))
285 ((something-else-entirely c e ...)
286 (if c (begin e ...)))))
289 For clarity, use one of the first two variants. Also note that since the pattern
290 variable will always match the macro itself (e.g., @code{cond1}), it is actually
291 left unbound in the template.
293 @subsubsection Hygiene
295 @code{syntax-rules} macros have a magical property: they preserve referential
296 transparency. When you read a macro definition, any free bindings in that macro
297 are resolved relative to the macro definition; and when you read a macro
298 instantiation, all free bindings in that expression are resolved relative to the
301 This property is sometimes known as @dfn{hygiene}, and it does aid in code
302 cleanliness. In your macro definitions, you can feel free to introduce temporary
303 variables, without worrying about inadvertantly introducing bindings into the
306 Consider the definition of @code{my-or} from the previous section:
315 ((my-or exp rest ...)
319 (my-or rest ...))))))
322 A naive expansion of @code{(let ((t #t)) (my-or #f t))} would yield:
332 Which clearly is not what we want. Somehow the @code{t} in the definition is
333 distinct from the @code{t} at the site of use; and it is indeed this distinction
334 that is maintained by the syntax expander, when expanding hygienic macros.
336 This discussion is mostly relevant in the context of traditional Lisp macros
337 (@pxref{Defmacros}), which do not preserve referential transparency. Hygiene
338 adds to the expressive power of Scheme.
340 @subsubsection Further Information
342 For a formal definition of @code{syntax-rules} and its pattern language, see
343 @xref{Macros, , Macros, r5rs, Revised(5) Report on the Algorithmic Language
346 @code{syntax-rules} macros are simple and clean, but do they have limitations.
347 They do not lend themselves to expressive error messages: patterns either match
348 or they don't. Their ability to generate code is limited to template-driven
349 expansion; often one needs to define a number of helper macros to get real work
350 done. Sometimes one wants to introduce a binding into the lexical context of the
351 generated code; this is impossible with @code{syntax-rules}. Relatedly, they
352 cannot programmatically generate identifiers.
354 The solution to all of these problems is to use @code{syntax-case} if you need
355 its features. But if for some reason you're stuck with @code{syntax-rules}, you
356 might enjoy Joe Marshall's
357 @uref{http://sites.google.com/site/evalapply/eccentric.txt,@code{syntax-rules}
358 Primer for the Merely Eccentric}.
361 @subsection Support for the @code{syntax-case} System
363 @code{syntax-case} macros are procedural syntax transformers, with a power
366 @deffn {Syntax} syntax-case syntax literals (pattern [guard] exp)...
367 Match the syntax object @var{syntax} against the given patterns, in order. If a
368 @var{pattern} matches, return the result of evaluating the associated @var{exp}.
371 Compare the following definitions of @code{when}:
377 (if test (begin e e* ...)))))
383 #'(if test (begin e e* ...))))))
386 Clearly, the @code{syntax-case} definition is similar to its @code{syntax-rules}
387 counterpart, and equally clearly there are some differences. The
388 @code{syntax-case} definition is wrapped in a @code{lambda}, a function of one
389 argument; that argument is passed to the @code{syntax-case} invocation; and the
390 ``return value'' of the macro has a @code{#'} prefix.
392 All of these differences stem from the fact that @code{syntax-case} does not
393 define a syntax transformer itself -- instead, @code{syntax-case} expressions
394 provide a way to destructure a @dfn{syntax object}, and to rebuild syntax
397 So the @code{lambda} wrapper is simply a leaky implementation detail, that
398 syntax transformers are just functions that transform syntax to syntax. This
399 should not be surprising, given that we have already described macros as
400 ``programs that write programs''. @code{syntax-case} is simply a way to take
401 apart and put together program text, and to be a valid syntax transformer it
402 needs to be wrapped in a procedure.
404 Unlike traditional Lisp macros (@pxref{Defmacros}), @code{syntax-case} macros
405 transform syntax objects, not raw Scheme forms. Recall the naive expansion of
406 @code{my-or} given in the previous section:
417 Raw Scheme forms simply don't have enough information to distinguish the first
418 two @code{t} instances in @code{(if t t t)} from the third @code{t}. So instead
419 of representing identifiers as symbols, the syntax expander represents
420 identifiers as annotated syntax objects, attaching such information to those
421 syntax objects as is needed to maintain referential transparency.
423 @deffn {Syntax} syntax form
424 Create a syntax object wrapping @var{form} within the current lexical context.
427 Syntax objects are typically created internally to the process of expansion, but
428 it is possible to create them outside of syntax expansion:
431 (syntax (foo bar baz))
432 @result{} #<some representation of that syntax>
436 However it is more common, and useful, to create syntax objects when building
437 output from a @code{syntax-case} expression.
444 (syntax (+ exp 1))))))
447 It is not strictly necessary for a @code{syntax-case} expression to return a
448 syntax object, because @code{syntax-case} expressions can be used in helper
449 functions, or otherwise used outside of syntax expansion itself. However a
450 syntax transformer procedure must return a syntax object, so most uses of
451 @code{syntax-case} do end up returning syntax objects.
453 Here in this case, the form that built the return value was @code{(syntax (+ exp
454 1))}. The interesting thing about this is that within a @code{syntax}
455 expression, any appearance of a pattern variable is substituted into the
456 resulting syntax object, carrying with it all relevant metadata from the source
457 expression, such as lexical identity and source location.
459 Indeed, a pattern variable may only be referenced from inside a @code{syntax}
460 form. The syntax expander would raise an error when defining @code{add1} if it
461 found @var{exp} referenced outside a @code{syntax} form.
463 Since @code{syntax} appears frequently in macro-heavy code, it has a special
464 reader macro: @code{#'}. @code{#'foo} is transformed by the reader into
465 @code{(syntax foo)}, just as @code{'foo} is tranformed into @code{(quote foo)}.
467 The pattern language used by @code{syntax-case} is conveniently the same
468 language used by @code{syntax-rules}. Given this, Guile actually defines
469 @code{syntax-rules} in terms of @code{syntax-case}:
472 (define-syntax syntax-rules
475 ((_ (k ...) ((keyword . pattern) template) ...)
477 (syntax-case x (k ...)
478 ((dummy . pattern) #'template)
484 @subsubsection Why @code{syntax-case}?
486 The examples we have shown thus far could just as well have been expressed with
487 @code{syntax-rules}, and have just shown that @code{syntax-case} is more
488 verbose, which is true. But there is a difference: @code{syntax-case} creates
489 @emph{procedural} macros, giving the full power of Scheme to the macro expander.
490 This has many practical applications.
492 A common desire is to be able to match a form only if it is an identifier. This
493 is impossible with @code{syntax-rules}, given the datum matching forms. But with
494 @code{syntax-case} it is easy:
496 @deffn {Scheme Procedure} identifier? syntax-object
497 Returns @code{#t} iff @var{syntax-object} is an identifier.
501 ;; relying on previous add1 definition
505 ((_ var) (identifier? #'var)
506 #'(set! var (add1 var))))))
511 (add1! "not-an-identifier") @result{} error
514 With @code{syntax-rules}, the error for @code{(add1! "not-an-identifier")} would
515 be something like ``invalid @code{set!}''. With @code{syntax-case}, it will say
516 something like ``invalid @code{add1!}'', because we attach the @dfn{guard
517 clause} to the pattern: @code{(identifier? #'var)}. This becomes more important
518 with more complicated macros. It is necessary to use @code{identifier?}, because
519 to the expander, an identifier is more than a bare symbol.
521 Note that even in the guard clause, we reference the @var{var} pattern variable
522 within a @code{syntax} form, via @code{#'var}.
524 Another common desire is to introduce bindings into the lexical context of the
525 output expression. One example would be in the so-called ``anaphoric macros'',
526 like @code{aif}. Anaphoric macros bind some expression to a well-known
527 identifier, often @code{it}, within their bodies. For example, in @code{(aif
528 (foo) (bar it))}, @code{it} would be bound to the result of @code{(foo)}.
530 To begin with, we should mention a solution that doesn't work:
539 (if it then else))))))
542 The reason that this doesn't work is that, by default, the expander will
543 preserve referential transparency; the @var{then} and @var{else} expressions
544 won't have access to the binding of @code{it}.
546 But they can, if we explicitly introduce a binding via @code{datum->syntax}.
548 @deffn {Scheme Procedure} datum->syntax for-syntax datum
549 Create a syntax object that wraps @var{datum}, within the lexical context
550 corresponding to the syntax object @var{for-syntax}.
553 For completeness, we should mention that it is possible to strip the metadata
554 from a syntax object, returning a raw Scheme datum:
556 @deffn {Scheme Procedure} syntax->datum syntax-object
557 Strip the metadata from @var{syntax-object}, returning its contents as a raw
561 In this case we want to introduce @code{it} in the context of the whole
562 expression, so we can create a syntax object as @code{(datum->syntax x 'it)},
563 where @code{x} is the whole expression, as passed to the transformer procedure.
565 Here's another solution that doesn't work:
568 ;; doesn't work either
573 (let ((it (datum->syntax x 'it)))
575 (if it then else)))))))
578 The reason that this one doesn't work is that there are really two environments
579 at work here -- the environment of pattern variables, as bound by
580 @code{syntax-case}, and the environment of lexical variables, as bound by normal
581 Scheme. Here we need to introduce a piece of Scheme's environment into that of
582 the syntax expander, and we can do so using @code{syntax-case} itself:
585 ;; works, but is obtuse
590 ;; invoking syntax-case on the generated
591 ;; syntax object to expose it to `syntax'
592 (syntax-case (datum->syntax x 'it) ()
595 (if it then else))))))))
597 (aif (getuid) (display it) (display "none")) (newline)
601 However there are easier ways to write this. @code{with-syntax} is often
604 @deffn {Syntax} with-syntax ((pat val)...) exp...
605 Bind patterns @var{pat} from their corresponding values @var{val}, within the
606 lexical context of @var{exp...}.
614 (with-syntax ((it (datum->syntax x 'it)))
616 (if it then else)))))))
620 As you might imagine, @code{with-syntax} is defined in terms of
621 @code{syntax-case}. But even that might be off-putting to you if you are an old
622 Lisp macro hacker, used to building macro output with @code{quasiquote}. The
623 issue is that @code{with-syntax} creates a separation between the point of
624 definition of a value and its point of substitution.
628 @pindex unsyntax-splicing
629 So for cases in which a @code{quasiquote} style makes more sense,
630 @code{syntax-case} also defines @code{quasisyntax}, and the related
631 @code{unsyntax} and @code{unsyntax-splicing}, abbreviated by the reader as
632 @code{#`}, @code{#,}, and @code{#,@@}, respectively.
634 For example, to define a macro that inserts a compile-time timestamp into a
635 source file, one may write:
638 (define-syntax display-compile-timestamp
643 (display "The compile timestamp was: ")
644 (display #,(current-time))
648 Finally, we should mention the following helper procedures defined by the core
649 of @code{syntax-case}:
651 @deffn {Scheme Procedure} bound-identifier=? a b
652 Returns @code{#t} iff the syntax objects @var{a} and @var{b} refer to the same
653 lexically-bound identifier.
656 @deffn {Scheme Procedure} free-identifier=? a b
657 Returns @code{#t} iff the syntax objects @var{a} and @var{b} refer to the same
661 @deffn {Scheme Procedure} generate-temporaries ls
662 Return a list of temporary identifiers as long as @var{ls} is long.
665 Readers interested in further information on @code{syntax-case} macros should
666 see R. Kent Dybvig's excellent @cite{The Scheme Programming Language}, either
667 edition 3 or 4, in the chapter on syntax. Dybvig was the primary author of the
668 @code{syntax-case} system. The book itself is available online at
669 @uref{http://scheme.com/tspl4/}.
672 @subsection Lisp-style Macro Definitions
674 The traditional way to define macros in Lisp is very similar to procedure
675 definitions. The key differences are that the macro definition body should
676 return a list that describes the transformed expression, and that the definition
677 is marked as a macro definition (rather than a procedure definition) by the use
678 of a different definition keyword: in Lisp, @code{defmacro} rather than
679 @code{defun}, and in Scheme, @code{define-macro} rather than @code{define}.
682 @fnindex define-macro
683 Guile supports this style of macro definition using both @code{defmacro}
684 and @code{define-macro}. The only difference between them is how the
685 macro name and arguments are grouped together in the definition:
688 (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
695 (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
699 The difference is analogous to the corresponding difference between
700 Lisp's @code{defun} and Scheme's @code{define}.
702 Having read the previous section on @code{syntax-case}, it's probably clear that
703 Guile actually implements defmacros in terms of @code{syntax-case}, applying the
704 transformer on the expression between invocations of @code{syntax->datum} and
705 @code{datum->syntax}. This realization leads us to the problem with defmacros,
706 that they do not preserve referential transparency. One can be careful to not
707 introduce bindings into expanded code, via liberal use of @code{gensym}, but
708 there is no getting around the lack of referential transparency for free
709 bindings in the macro itself.
711 Even a macro as simple as our @code{when} from before is difficult to get right:
714 (define-macro (when cond exp . rest)
716 (begin ,exp . ,rest)))
718 (when #f (display "Launching missiles!\n"))
722 (when #f (display "Launching missiles!\n")))
723 @print{} Launching missiles!
724 @result{} (#f #<unspecified>)
727 Guile's perspective is that defmacros have had a good run, but that modern
728 macros should be written with @code{syntax-rules} or @code{syntax-case}. There
729 are still many uses of defmacros within Guile itself, but we will be phasing
730 them out over time. Of course we won't take away @code{defmacro} or
731 @code{define-macro} themselves, as there is lots of code out there that uses
735 @node Identifier Macros
736 @subsection Identifier Macros
738 When the syntax expander sees a form in which the first element is a macro, the
739 whole form gets passed to the macro's syntax transformer. One may visualize this
743 (define-syntax foo foo-transformer)
746 (foo-transformer #'(foo @var{arg}...))
749 If, on the other hand, a macro is referenced in some other part of a form, the
750 syntax transformer is invoked with only the macro reference, not the whole form.
753 (define-syntax foo foo-transformer)
756 (foo-transformer #'foo)
759 This allows bare identifier references to be replaced programmatically via a
760 macro. @code{syntax-rules} provides some syntax to effect this transformation
763 @deffn {Syntax} identifier-syntax exp
764 Returns a macro transformer that will replace occurences of the macro with
768 For example, if you are importing external code written in terms of @code{fx+},
769 the fixnum addition operator, but Guile doesn't have @code{fx+}, you may use the
770 following to replace @code{fx+} with @code{+}:
773 (define-syntax fx+ (identifier-syntax +))
776 There is also special support for recognizing identifiers on the
777 left-hand side of a @code{set!} expression, as in the following:
780 (define-syntax foo foo-transformer)
783 (foo-transformer #'(set! foo @var{val}))
784 ;; iff foo-transformer is a "variable transformer"
787 As the example notes, the transformer procedure must be explicitly
788 marked as being a ``variable transformer'', as most macros aren't
789 written to discriminate on the form in the operator position.
791 @deffn {Scheme Procedure} make-variable-transformer transformer
792 Mark the @var{transformer} procedure as being a ``variable
793 transformer''. In practice this means that, when bound to a syntactic
794 keyword, it may detect references to that keyword on the left-hand-side
799 (define-syntax bar-alias
800 (make-variable-transformer
802 (syntax-case x (set!)
803 ((set! var val) #'(set! bar val))
804 ((var arg ...) #'(bar arg ...))
805 (var (identifier? #'var) #'bar)))))
807 bar-alias @result{} 10
811 bar-alias @result{} 30
815 There is an extension to identifer-syntax which allows it to handle the
816 @code{set!} case as well:
818 @deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2)
819 Create a variable transformer. The first clause is used for references
820 to the variable in operator or operand position, and the second for
821 appearances of the variable on the left-hand-side of an assignment.
823 For example, the previous @code{bar-alias} example could be expressed
824 more succinctly like this:
827 (define-syntax bar-alias
830 ((set! var val) (set! bar val))))
834 As before, the templates in @code{identifier-syntax} forms do not need
835 wrapping in @code{#'} syntax forms.
840 @subsection Eval-when
842 As @code{syntax-case} macros have the whole power of Scheme available to them,
843 they present a problem regarding time: when a macro runs, what parts of the
844 program are available for the macro to use?
846 The default answer to this question is that when you import a module (via
847 @code{define-module} or @code{use-modules}), that module will be loaded up at
848 expansion-time, as well as at run-time. Additionally, top-level syntactic
849 definitions within one compilation unit made by @code{define-syntax} are also
850 evaluated at expansion time, in the order that they appear in the compilation
853 But if a syntactic definition needs to call out to a normal procedure at
854 expansion-time, it might well need need special declarations to indicate that
855 the procedure should be made available at expansion-time.
857 For example, the following code will work at a REPL, but not in a file:
861 (use-modules (srfi srfi-19))
862 (define (date) (date->string (current-date)))
863 (define-syntax %date (identifier-syntax (date)))
864 (define *compilation-date* %date)
867 It works at a REPL because the expressions are evaluated one-by-one, in order,
868 but if placed in a file, the expressions are expanded one-by-one, but not
869 evaluated until the compiled file is loaded.
871 The fix is to use @code{eval-when}.
874 ;; correct: using eval-when
875 (use-modules (srfi srfi-19))
876 (eval-when (compile load eval)
877 (define (date) (date->string (current-date))))
878 (define-syntax %date (identifier-syntax (date)))
879 (define *compilation-date* %date)
882 @deffn {Syntax} eval-when conditions exp...
883 Evaluate @var{exp...} under the given @var{conditions}. Valid conditions include
884 @code{eval}, @code{load}, and @code{compile}. If you need to use
885 @code{eval-when}, use it with all three conditions, as in the above example.
886 Other uses of @code{eval-when} may void your warranty or poison your cat.
889 @node Internal Macros
890 @subsection Internal Macros
892 @deffn {Scheme Procedure} make-syntax-transformer name type binding
893 Construct a syntax transformer object. This is part of Guile's low-level support
897 @deffn {Scheme Procedure} macro? obj
898 @deffnx {C Function} scm_macro_p (obj)
899 Return @code{#t} iff @var{obj} is a syntax transformer.
901 Note that it's a bit difficult to actually get a macro as a first-class object;
902 simply naming it (like @code{case}) will produce a syntax error. But it is
903 possible to get these objects using @code{module-ref}:
906 (macro? (module-ref (current-module) 'case))
911 @deffn {Scheme Procedure} macro-type m
912 @deffnx {C Function} scm_macro_type (m)
913 Return the @var{type} that was given when @var{m} was constructed, via
914 @code{make-syntax-transformer}.
917 @deffn {Scheme Procedure} macro-name m
918 @deffnx {C Function} scm_macro_name (m)
919 Return the name of the macro @var{m}.
922 @deffn {Scheme Procedure} macro-binding m
923 @deffnx {C Function} scm_macro_binding (m)
924 Return the binding of the macro @var{m}.
927 @deffn {Scheme Procedure} macro-transformer m
928 @deffnx {C Function} scm_macro_transformer (m)
929 Return the transformer of the macro @var{m}. This will return a procedure, for
930 which one may ask the docstring. That's the whole reason this section is
931 documented. Actually a part of the result of @code{macro-binding}.
936 @c TeX-master: "guile.texi"