### 3.4 Macros That Work ¶

`(require 'macros-that-work)`

Macros That Work differs from the other R4RS macro implementations in that it does not expand derived expression types to primitive expression types.

Function: macro:expand expression ¶
Function: macwork:expand expression ¶

  Takes an R4RS expression, macro-expands it, and returns the result of the macro expansion.

Function: macro:eval expression ¶
Function: macwork:eval expression ¶

  `macro:eval` returns the value of expression in the current top level environment. expression can contain macro definitions. Side effects of expression will affect the top level environment.

Procedure: macro:load filename ¶
Procedure: macwork:load filename ¶

  filename should be a string. If filename names an existing file, the `macro:load` procedure reads Scheme source code expressions and definitions from the file and evaluates them sequentially. These source code expressions and definitions may contain macro definitions. The `macro:load` procedure does not affect the values returned by `current-input-port`, `current-error-port`, and `current-output-port`.

References:

The Revised^4 Report on the Algorithmic Language Scheme Clinger and Rees [editors]. To appear in LISP Pointers. Also available as a technical report from the University of Oregon, MIT AI Lab, and Cornell.

Macros That Work. Clinger and Rees. POPL ’91.

The supported syntax differs from the R4RS in that vectors are allowed as patterns and as templates and are not allowed as pattern or template data.

    transformer spec  →  (syntax-rules literals rules)

    rules  →  ()
             |  (rule . rules)

    rule  →  (pattern template)

    pattern  →  pattern_var      ; a symbol not in literals
               |  symbol           ; a symbol in literals
               |  ()
               |  (pattern . pattern)
               |  (ellipsis_pattern)
               |  #(pattern*)                     ; extends R4RS
               |  #(pattern* ellipsis_pattern)    ; extends R4RS
               |  pattern_datum

    template  →  pattern_var
                |  symbol
                |  ()
                |  (template2 . template2)
                |  #(template*)                   ; extends R4RS
                |  pattern_datum

    template2  →  template
                 |  ellipsis_template

    pattern_datum  →  string                    ; no vector
                     |  character
                     |  boolean
                     |  number

    ellipsis_pattern  → pattern ...

    ellipsis_template  →  template ...

    pattern_var  →  symbol   ; not in literals

    literals  →  ()
                |  (symbol . literals)

#### 3.4.1 Definitions ¶

Scope of an ellipsis

  Within a pattern or template, the scope of an ellipsis (`...`) is the pattern or template that appears to its left.

Rank of a pattern variable

  The rank of a pattern variable is the number of ellipses within whose scope it appears in the pattern.

Rank of a subtemplate

  The rank of a subtemplate is the number of ellipses within whose scope it appears in the template.

Template rank of an occurrence of a pattern variable

  The template rank of an occurrence of a pattern variable within a template is the rank of that occurrence, viewed as a subtemplate.

Variables bound by a pattern

  The variables bound by a pattern are the pattern variables that appear within it.

Referenced variables of a subtemplate

  The referenced variables of a subtemplate are the pattern variables that appear within it.

Variables opened by an ellipsis template

  The variables opened by an ellipsis template are the referenced pattern variables whose rank is greater than the rank of the ellipsis template.

#### 3.4.2 Restrictions ¶

No pattern variable appears more than once within a pattern.

For every occurrence of a pattern variable within a template, the template rank of the occurrence must be greater than or equal to the pattern variable’s rank.

Every ellipsis template must open at least one variable.

For every ellipsis template, the variables opened by an ellipsis template must all be bound to sequences of the same length.

The compiled form of a rule is

    rule  →  (pattern template inserted)

    pattern  →  pattern_var
               |  symbol
               |  ()
               |  (pattern . pattern)
               |  ellipsis_pattern
               |  #(pattern)
               |  pattern_datum

    template  →  pattern_var
                |  symbol
                |  ()
                |  (template2 . template2)
                |  #(pattern)
                |  pattern_datum

    template2  →  template
                 |  ellipsis_template

    pattern_datum  →  string
                     |  character
                     |  boolean
                     |  number

    pattern_var  →  #(V symbol rank)

    ellipsis_pattern  →  #(E pattern pattern_vars)

    ellipsis_template  →  #(E template pattern_vars)

    inserted  →  ()
                |  (symbol . inserted)

    pattern_vars  →  ()
                    |  (pattern_var . pattern_vars)

    rank  →  exact non-negative integer

where V and E are unforgeable values.

The pattern variables associated with an ellipsis pattern are the variables bound by the pattern, and the pattern variables associated with an ellipsis template are the variables opened by the ellipsis template.

If the template contains a big chunk that contains no pattern variables or inserted identifiers, then the big chunk will be copied unnecessarily. That shouldn’t matter very often.