.SCM File Format – Macros

Hygiene

Macros defined with the pattern language are hygienic and referentially transparent, so they keep Scheme’s lexical scoping:

• if a transformer inserts a binding for an identifier, the identifier is renamed throughout its scope, so it cannot capture a variable of the code that uses the macro;
• if a transformer inserts a free reference to an identifier, it refers to the binding visible where the macro was defined, whatever bindings surround the use.

The syntactic keyword of a macro can shadow a variable, and a local variable can shadow a keyword. Implementations may offer other kinds of macro.

Defining and binding keywords

The pattern language

A syntax-rules transformer holds rules, each (pattern template). A macro use is matched against the patterns from the first rule to the last, and the first that matches is rewritten by its template. The pattern is a list; its first element is the keyword, which takes no part in the match and is neither a pattern variable nor a literal.

Patterns

Templates

(define-syntax swap!
  (syntax-rules ()
    ((_ a b)
     (let ((tmp a))
       (set! a b)
       (set! b tmp)))))

(define-syntax my-or
  (syntax-rules ()
    ((_) #f)
    ((_ e) e)
    ((_ e r ...)
     (let ((t e)) (if t t (my-or r ...))))))

(define-syntax be-like-begin
  (syntax-rules ()
    ((be-like-begin name)
     (define-syntax name
       (syntax-rules ()
         ((name expr (... ...))
          (begin expr (... ...))))))))

(be-like-begin sequence)
(sequence 1 2 3 4)   ; 4

Hygiene decides the case below: a local variable named => is not the keyword => that cond looks for, so cond treats the clause as an ordinary test and expression.

(let ((=> #f))
  (cond (#t => 'ok)))      ; ok

An identifier in a pattern is a pattern variable unless it is _, a literal, or the ellipsis. In R7RS a custom ellipsis lets a macro that generates macros avoid (... ...): (syntax-rules ::: () ...) uses :::, and the identifier ... is then an ordinary one; if the ellipsis is also listed among the literals it matches itself.

In the viewer the pattern variables are coloured as variables, ... and _ as syntax, the literals as syntax, and the template as code, so that a macro that expands into a let shows the let as syntax.

syntax-case (R6RS)

R6RS adds the procedural macro system of (rnrs syntax-case). A transformer is a procedure from a syntax object to a syntax object, and syntax-case takes it apart by pattern while ordinary Scheme code builds the result. The patterns are those of syntax-rules, and a clause may have a fender between the pattern and the template, an expression that must be true for the clause to be chosen.

(define-syntax my-if
  (lambda (stx)
    (syntax-case stx ()
      ((_ c t e) #'(cond (c t) (else e))))))

(define-syntax loop
  (lambda (x)
    (syntax-case x ()
      ((k e ...)
       (with-syntax ((break (datum->syntax #'k 'break)))
         #'(call-with-current-continuation
             (lambda (break)
               (let f () e ... (f)))))))))

R6RS programs and libraries run the code of a macro transformer at expansion time, in a separate phase from run time. A library imports the bindings that a transformer needs with a (for (library) expand) import set (see Libraries and modules). R7RS-small has no phases and no procedural macros. The viewer reads the patterns of syntax-case clauses as it reads those of syntax-rules and the templates as code.

Macro systems of the implementations

Macros and the reader

A macro sees data, not text: it cannot tell #t from #true or [ from (, since the reader has already turned them into the same object. A definition may expand into several definitions through begin. A macro cannot change how a file is read; some implementations (Guile, Racket, Gambit) let a program change the reader, which the viewer does not follow.

Not described

Known, not yet covered

• Reference: the matching and expansion algorithms of the reports (what “matches” means for every pattern, in R7RS section 4.3.2 and the R6RS syntax-case chapter) are summarised in the tables and not described step by step.
• Reference: the macro transformers of the implementations are named in the table; their procedure interfaces are not described. The table was written from memory of their manuals, which were not read, and which implementations support which system should be checked before relying on it.
• Reference: the SRFIs named in the table were not read; their titles are in the SRFI page, from the index.
• Viewer: pattern variables of er-macro-transformer-style transformers are procedure parameters, and the viewer colours them as such; the input form is not coloured as data.

See also

• Expressions and special forms – the forms macros commonly rebuild
• Libraries and modules – phases and exporting macros
• SRFI – macro-related SRFIs