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.
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 inadvertantly 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 Further Information
341 For a formal definition of @code{syntax-rules} and its pattern language, see
342 @xref{Macros, , Macros, r5rs, Revised(5) Report on the Algorithmic Language
345 @code{syntax-rules} macros are simple and clean, but do they have limitations.
346 They do not lend themselves to expressive error messages: patterns either match
347 or they don't. Their ability to generate code is limited to template-driven
348 expansion; often one needs to define a number of helper macros to get real work
349 done. Sometimes one wants to introduce a binding into the lexical context of the
350 generated code; this is impossible with @code{syntax-rules}. Relatedly, they
351 cannot programmatically generate identifiers.
353 The solution to all of these problems is to use @code{syntax-case} if you need
354 its features. But if for some reason you're stuck with @code{syntax-rules}, you
355 might enjoy Joe Marshall's
356 @uref{http://sites.google.com/site/evalapply/eccentric.txt,@code{syntax-rules}
357 Primer for the Merely Eccentric}.
360 @subsection Support for the @code{syntax-case} System
362 @code{syntax-case} macros are procedural syntax transformers, with a power
365 @deffn {Syntax} syntax-case syntax literals (pattern [guard] exp)...
366 Match the syntax object @var{syntax} against the given patterns, in order. If a
367 @var{pattern} matches, return the result of evaluating the associated @var{exp}.
370 Compare the following definitions of @code{when}:
376 (if test (begin e e* ...)))))
382 #'(if test (begin e e* ...))))))
385 Clearly, the @code{syntax-case} definition is similar to its @code{syntax-rules}
386 counterpart, and equally clearly there are some differences. The
387 @code{syntax-case} definition is wrapped in a @code{lambda}, a function of one
388 argument; that argument is passed to the @code{syntax-case} invocation; and the
389 ``return value'' of the macro has a @code{#'} prefix.
391 All of these differences stem from the fact that @code{syntax-case} does not
392 define a syntax transformer itself -- instead, @code{syntax-case} expressions
393 provide a way to destructure a @dfn{syntax object}, and to rebuild syntax
396 So the @code{lambda} wrapper is simply a leaky implementation detail, that
397 syntax transformers are just functions that transform syntax to syntax. This
398 should not be surprising, given that we have already described macros as
399 ``programs that write programs''. @code{syntax-case} is simply a way to take
400 apart and put together program text, and to be a valid syntax transformer it
401 needs to be wrapped in a procedure.
403 Unlike traditional Lisp macros (@pxref{Defmacros}), @code{syntax-case} macros
404 transform syntax objects, not raw Scheme forms. Recall the naive expansion of
405 @code{my-or} given in the previous section:
416 Raw Scheme forms simply don't have enough information to distinguish the first
417 two @code{t} instances in @code{(if t t t)} from the third @code{t}. So instead
418 of representing identifiers as symbols, the syntax expander represents
419 identifiers as annotated syntax objects, attaching such information to those
420 syntax objects as is needed to maintain referential transparency.
422 @deffn {Syntax} syntax form
423 Create a syntax object wrapping @var{form} within the current lexical context.
426 Syntax objects are typically created internally to the process of expansion, but
427 it is possible to create them outside of syntax expansion:
430 (syntax (foo bar baz))
431 @result{} #<some representation of that syntax>
435 However it is more common, and useful, to create syntax objects when building
436 output from a @code{syntax-case} expression.
443 (syntax (+ exp 1))))))
446 It is not strictly necessary for a @code{syntax-case} expression to return a
447 syntax object, because @code{syntax-case} expressions can be used in helper
448 functions, or otherwise used outside of syntax expansion itself. However a
449 syntax transformer procedure must return a syntax object, so most uses of
450 @code{syntax-case} do end up returning syntax objects.
452 Here in this case, the form that built the return value was @code{(syntax (+ exp
453 1))}. The interesting thing about this is that within a @code{syntax}
454 expression, any appearance of a pattern variable is substituted into the
455 resulting syntax object, carrying with it all relevant metadata from the source
456 expression, such as lexical identity and source location.
458 Indeed, a pattern variable may only be referenced from inside a @code{syntax}
459 form. The syntax expander would raise an error when defining @code{add1} if it
460 found @var{exp} referenced outside a @code{syntax} form.
462 Since @code{syntax} appears frequently in macro-heavy code, it has a special
463 reader macro: @code{#'}. @code{#'foo} is transformed by the reader into
464 @code{(syntax foo)}, just as @code{'foo} is tranformed into @code{(quote foo)}.
466 The pattern language used by @code{syntax-case} is conveniently the same
467 language used by @code{syntax-rules}. Given this, Guile actually defines
468 @code{syntax-rules} in terms of @code{syntax-case}:
471 (define-syntax syntax-rules
474 ((_ (k ...) ((keyword . pattern) template) ...)
476 (syntax-case x (k ...)
477 ((dummy . pattern) #'template)
483 @subsubsection Why @code{syntax-case}?
485 The examples we have shown thus far could just as well have been expressed with
486 @code{syntax-rules}, and have just shown that @code{syntax-case} is more
487 verbose, which is true. But there is a difference: @code{syntax-case} creates
488 @emph{procedural} macros, giving the full power of Scheme to the macro expander.
489 This has many practical applications.
491 A common desire is to be able to match a form only if it is an identifier. This
492 is impossible with @code{syntax-rules}, given the datum matching forms. But with
493 @code{syntax-case} it is easy:
495 @deffn {Scheme Procedure} identifier? syntax-object
496 Returns @code{#t} iff @var{syntax-object} is an identifier.
500 ;; relying on previous add1 definition
504 ((_ var) (identifier? #'var)
505 #'(set! var (add1 var))))))
510 (add1! "not-an-identifier") @result{} error
513 With @code{syntax-rules}, the error for @code{(add1! "not-an-identifier")} would
514 be something like ``invalid @code{set!}''. With @code{syntax-case}, it will say
515 something like ``invalid @code{add1!}'', because we attach the @dfn{guard
516 clause} to the pattern: @code{(identifier? #'var)}. This becomes more important
517 with more complicated macros. It is necessary to use @code{identifier?}, because
518 to the expander, an identifier is more than a bare symbol.
520 Note that even in the guard clause, we reference the @var{var} pattern variable
521 within a @code{syntax} form, via @code{#'var}.
523 Another common desire is to introduce bindings into the lexical context of the
524 output expression. One example would be in the so-called ``anaphoric macros'',
525 like @code{aif}. Anaphoric macros bind some expression to a well-known
526 identifier, often @code{it}, within their bodies. For example, in @code{(aif
527 (foo) (bar it))}, @code{it} would be bound to the result of @code{(foo)}.
529 To begin with, we should mention a solution that doesn't work:
538 (if it then else))))))
541 The reason that this doesn't work is that, by default, the expander will
542 preserve referential transparency; the @var{then} and @var{else} expressions
543 won't have access to the binding of @code{it}.
545 But they can, if we explicitly introduce a binding via @code{datum->syntax}.
547 @deffn {Scheme Procedure} datum->syntax for-syntax datum
548 Create a syntax object that wraps @var{datum}, within the lexical context
549 corresponding to the syntax object @var{for-syntax}.
552 For completeness, we should mention that it is possible to strip the metadata
553 from a syntax object, returning a raw Scheme datum:
555 @deffn {Scheme Procedure} syntax->datum syntax-object
556 Strip the metadata from @var{syntax-object}, returning its contents as a raw
560 In this case we want to introduce @code{it} in the context of the whole
561 expression, so we can create a syntax object as @code{(datum->syntax x 'it)},
562 where @code{x} is the whole expression, as passed to the transformer procedure.
564 Here's another solution that doesn't work:
567 ;; doesn't work either
572 (let ((it (datum->syntax x 'it)))
574 (if it then else)))))))
577 The reason that this one doesn't work is that there are really two environments
578 at work here -- the environment of pattern variables, as bound by
579 @code{syntax-case}, and the environment of lexical variables, as bound by normal
580 Scheme. Here we need to introduce a piece of Scheme's environment into that of
581 the syntax expander, and we can do so using @code{syntax-case} itself:
584 ;; works, but is obtuse
589 ;; invoking syntax-case on the generated
590 ;; syntax object to expose it to `syntax'
591 (syntax-case (datum->syntax x 'it) ()
594 (if it then else))))))))
596 (aif (getuid) (display it) (display "none")) (newline)
600 However there are easier ways to write this. @code{with-syntax} is often
603 @deffn {Syntax} with-syntax ((pat val)...) exp...
604 Bind patterns @var{pat} from their corresponding values @var{val}, within the
605 lexical context of @var{exp...}.
613 (with-syntax ((it (datum->syntax x 'it)))
615 (if it then else)))))))
619 As you might imagine, @code{with-syntax} is defined in terms of
620 @code{syntax-case}. But even that might be off-putting to you if you are an old
621 Lisp macro hacker, used to building macro output with @code{quasiquote}. The
622 issue is that @code{with-syntax} creates a separation between the point of
623 definition of a value and its point of substitution.
627 @pindex unsyntax-splicing
628 So for cases in which a @code{quasiquote} style makes more sense,
629 @code{syntax-case} also defines @code{quasisyntax}, and the related
630 @code{unsyntax} and @code{unsyntax-splicing}, abbreviated by the reader as
631 @code{#`}, @code{#,}, and @code{#,@@}, respectively.
633 For example, to define a macro that inserts a compile-time timestamp into a
634 source file, one may write:
637 (define-syntax display-compile-timestamp
642 (display "The compile timestamp was: ")
643 (display #,(current-time))
647 Finally, we should mention the following helper procedures defined by the core
648 of @code{syntax-case}:
650 @deffn {Scheme Procedure} bound-identifier=? a b
651 Returns @code{#t} iff the syntax objects @var{a} and @var{b} refer to the same
652 lexically-bound identifier.
655 @deffn {Scheme Procedure} free-identifier=? a b
656 Returns @code{#t} iff the syntax objects @var{a} and @var{b} refer to the same
660 @deffn {Scheme Procedure} generate-temporaries ls
661 Return a list of temporary identifiers as long as @var{ls} is long.
664 Readers interested in further information on @code{syntax-case} macros should
665 see R. Kent Dybvig's excellent @cite{The Scheme Programming Language}, either
666 edition 3 or 4, in the chapter on syntax. Dybvig was the primary author of the
667 @code{syntax-case} system. The book itself is available online at
668 @uref{http://scheme.com/tspl4/}.
671 @subsection Lisp-style Macro Definitions
673 The traditional way to define macros in Lisp is very similar to procedure
674 definitions. The key differences are that the macro definition body should
675 return a list that describes the transformed expression, and that the definition
676 is marked as a macro definition (rather than a procedure definition) by the use
677 of a different definition keyword: in Lisp, @code{defmacro} rather than
678 @code{defun}, and in Scheme, @code{define-macro} rather than @code{define}.
681 @fnindex define-macro
682 Guile supports this style of macro definition using both @code{defmacro}
683 and @code{define-macro}. The only difference between them is how the
684 macro name and arguments are grouped together in the definition:
687 (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
694 (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
698 The difference is analogous to the corresponding difference between
699 Lisp's @code{defun} and Scheme's @code{define}.
701 Having read the previous section on @code{syntax-case}, it's probably clear that
702 Guile actually implements defmacros in terms of @code{syntax-case}, applying the
703 transformer on the expression between invocations of @code{syntax->datum} and
704 @code{datum->syntax}. This realization leads us to the problem with defmacros,
705 that they do not preserve referential transparency. One can be careful to not
706 introduce bindings into expanded code, via liberal use of @code{gensym}, but
707 there is no getting around the lack of referential transparency for free
708 bindings in the macro itself.
710 Even a macro as simple as our @code{when} from before is difficult to get right:
713 (define-macro (when cond exp . rest)
715 (begin ,exp . ,rest)))
717 (when #f (display "Launching missiles!\n"))
721 (when #f (display "Launching missiles!\n")))
722 @print{} Launching missiles!
723 @result{} (#f #<unspecified>)
726 Guile's perspective is that defmacros have had a good run, but that modern
727 macros should be written with @code{syntax-rules} or @code{syntax-case}. There
728 are still many uses of defmacros within Guile itself, but we will be phasing
729 them out over time. Of course we won't take away @code{defmacro} or
730 @code{define-macro} themselves, as there is lots of code out there that uses
734 @node Identifier Macros
735 @subsection Identifier Macros
737 When the syntax expander sees a form in which the first element is a macro, the
738 whole form gets passed to the macro's syntax transformer. One may visualize this
742 (define-syntax foo foo-transformer)
745 (foo-transformer #'(foo @var{arg}...))
748 If, on the other hand, a macro is referenced in some other part of a form, the
749 syntax transformer is invoked with only the macro reference, not the whole form.
752 (define-syntax foo foo-transformer)
755 (foo-transformer #'foo)
758 This allows bare identifier references to be replaced programmatically via a
759 macro. @code{syntax-rules} provides some syntax to effect this transformation
762 @deffn {Syntax} identifier-syntax exp
763 Returns a macro transformer that will replace occurences of the macro with
767 For example, if you are importing external code written in terms of @code{fx+},
768 the fixnum addition operator, but Guile doesn't have @code{fx+}, you may use the
769 following to replace @code{fx+} with @code{+}:
772 (define-syntax fx+ (identifier-syntax +))
775 There is also special support for recognizing identifiers on the
776 left-hand side of a @code{set!} expression, as in the following:
779 (define-syntax foo foo-transformer)
782 (foo-transformer #'(set! foo @var{val}))
783 ;; iff foo-transformer is a "variable transformer"
786 As the example notes, the transformer procedure must be explicitly
787 marked as being a ``variable transformer'', as most macros aren't
788 written to discriminate on the form in the operator position.
790 @deffn {Scheme Procedure} make-variable-transformer transformer
791 Mark the @var{transformer} procedure as being a ``variable
792 transformer''. In practice this means that, when bound to a syntactic
793 keyword, it may detect references to that keyword on the left-hand-side
798 (define-syntax bar-alias
799 (make-variable-transformer
801 (syntax-case x (set!)
802 ((set! var val) #'(set! bar val))
803 ((var arg ...) #'(bar arg ...))
804 (var (identifier? #'var) #'bar)))))
806 bar-alias @result{} 10
810 bar-alias @result{} 30
814 There is an extension to identifer-syntax which allows it to handle the
815 @code{set!} case as well:
817 @deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2)
818 Create a variable transformer. The first clause is used for references
819 to the variable in operator or operand position, and the second for
820 appearances of the variable on the left-hand-side of an assignment.
822 For example, the previous @code{bar-alias} example could be expressed
823 more succinctly like this:
826 (define-syntax bar-alias
829 ((set! var val) (set! bar val))))
833 As before, the templates in @code{identifier-syntax} forms do not need
834 wrapping in @code{#'} syntax forms.
839 @subsection Eval-when
841 As @code{syntax-case} macros have the whole power of Scheme available to them,
842 they present a problem regarding time: when a macro runs, what parts of the
843 program are available for the macro to use?
845 The default answer to this question is that when you import a module (via
846 @code{define-module} or @code{use-modules}), that module will be loaded up at
847 expansion-time, as well as at run-time. Additionally, top-level syntactic
848 definitions within one compilation unit made by @code{define-syntax} are also
849 evaluated at expansion time, in the order that they appear in the compilation
852 But if a syntactic definition needs to call out to a normal procedure at
853 expansion-time, it might well need need special declarations to indicate that
854 the procedure should be made available at expansion-time.
856 For example, the following code will work at a REPL, but not in a file:
860 (use-modules (srfi srfi-19))
861 (define (date) (date->string (current-date)))
862 (define-syntax %date (identifier-syntax (date)))
863 (define *compilation-date* %date)
866 It works at a REPL because the expressions are evaluated one-by-one, in order,
867 but if placed in a file, the expressions are expanded one-by-one, but not
868 evaluated until the compiled file is loaded.
870 The fix is to use @code{eval-when}.
873 ;; correct: using eval-when
874 (use-modules (srfi srfi-19))
875 (eval-when (compile load eval)
876 (define (date) (date->string (current-date))))
877 (define-syntax %date (identifier-syntax (date)))
878 (define *compilation-date* %date)
881 @deffn {Syntax} eval-when conditions exp...
882 Evaluate @var{exp...} under the given @var{conditions}. Valid conditions include
883 @code{eval}, @code{load}, and @code{compile}. If you need to use
884 @code{eval-when}, use it with all three conditions, as in the above example.
885 Other uses of @code{eval-when} may void your warranty or poison your cat.
888 @node Internal Macros
889 @subsection Internal Macros
891 @deffn {Scheme Procedure} make-syntax-transformer name type binding
892 Construct a syntax transformer object. This is part of Guile's low-level support
896 @deffn {Scheme Procedure} macro? obj
897 @deffnx {C Function} scm_macro_p (obj)
898 Return @code{#t} iff @var{obj} is a syntax transformer.
900 Note that it's a bit difficult to actually get a macro as a first-class object;
901 simply naming it (like @code{case}) will produce a syntax error. But it is
902 possible to get these objects using @code{module-ref}:
905 (macro? (module-ref (current-module) 'case))
910 @deffn {Scheme Procedure} macro-type m
911 @deffnx {C Function} scm_macro_type (m)
912 Return the @var{type} that was given when @var{m} was constructed, via
913 @code{make-syntax-transformer}.
916 @deffn {Scheme Procedure} macro-name m
917 @deffnx {C Function} scm_macro_name (m)
918 Return the name of the macro @var{m}.
921 @deffn {Scheme Procedure} macro-binding m
922 @deffnx {C Function} scm_macro_binding (m)
923 Return the binding of the macro @var{m}.
926 @deffn {Scheme Procedure} macro-transformer m
927 @deffnx {C Function} scm_macro_transformer (m)
928 Return the transformer of the macro @var{m}. This will return a procedure, for
929 which one may ask the docstring. That's the whole reason this section is
930 documented. Actually a part of the result of @code{macro-binding}.
935 @c TeX-master: "guile.texi"