Internal Macros - Guile Reference Manual

Previous: Syntax Case, Up: Procedures and Macros

5.8.9 Internal Representation of Macros and Syntax

Internally, Guile uses three different flavors of macros. The three flavors are called acro (or syntax), macro and mmacro.

Given the expression

     (foo ...)

with foo being some flavor of macro, one of the following things will happen when the expression is evaluated.

When foo has been defined to be an acro, the procedure used in the acro definition of foo is passed the whole expression and the current lexical environment, and whatever that procedure returns is the value of evaluating the expression. You can think of this a procedure that receives its argument as an unevaluated expression.
When foo has been defined to be a macro, the procedure used in the macro definition of foo is passed the whole expression and the current lexical environment, and whatever that procedure returns is evaluated again. That is, the procedure should return a valid Scheme expression.
When foo has been defined to be a mmacro, the procedure used in the mmacro definition of `foo' is passed the whole expression and the current lexical environment, and whatever that procedure returns replaces the original expression. Evaluation then starts over from the new expression that has just been returned.

The key difference between a macro and a mmacro is that the expression returned by a mmacro procedure is remembered (or memoized) so that the expansion does not need to be done again next time the containing code is evaluated.

The primitives procedure->syntax, procedure->macro and procedure->memoizing-macro are used to construct acros, macros and mmacros respectively. However, if you do not have a very special reason to use one of these primitives, you should avoid them: they are very specific to Guile's current implementation and therefore likely to change. Use defmacro, define-macro (see Macros) or define-syntax (see Syntax Rules) instead. (In low level terms, defmacro, define-macro and define-syntax are all implemented as mmacros.)

— Scheme Procedure: procedure->syntax code
— C Function: scm_makacro (code)

Return a macro which, when a symbol defined to this value appears as the first symbol in an expression, returns the result of applying code to the expression and the environment.

— Scheme Procedure: procedure->macro code
— C Function: scm_makmacro (code)

Return a macro which, when a symbol defined to this value appears as the first symbol in an expression, evaluates the result of applying code to the expression and the environment. For example:
          (define trace
            (procedure->macro
              (lambda (x env)
                `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
          
          (trace foo)
          ==
          (set! foo (tracef foo 'foo)).
     

— Scheme Procedure: procedure->memoizing-macro code
— C Function: scm_makmmacro (code)

Return a macro which, when a symbol defined to this value appears as the first symbol in an expression, evaluates the result of applying code to the expression and the environment. procedure->memoizing-macro is the same as procedure->macro, except that the expression returned by code replaces the original macro expression in the memoized form of the containing code.

In the following primitives, acro flavor macros are referred to as syntax transformers.

— Scheme Procedure: macro? obj
— C Function: scm_macro_p (obj)

Return #t if obj is a regular macro, a memoizing macro or a syntax transformer.

— Scheme Procedure: macro-type m
— C Function: scm_macro_type (m)

Return one of the symbols syntax, macro or macro!, depending on whether m is a syntax transformer, a regular macro, or a memoizing macro, respectively. If m is not a macro, #f is returned.

— Scheme Procedure: macro-name m
— C Function: scm_macro_name (m)

Return the name of the macro m.

— Scheme Procedure: macro-transformer m
— C Function: scm_macro_transformer (m)

Return the transformer of the macro m.

— Scheme Procedure: cons-source xorig x y
— C Function: scm_cons_source (xorig, x, y)

Create and return a new pair whose car and cdr are x and y. Any source properties associated with xorig are also associated with the new pair.