6.8.3 Support for the syntax-case System

syntax-case macros are procedural syntax transformers, with a power worthy of Scheme.

Syntax: syntax-case syntax literals (pattern [guard] exp) …

Match the syntax object syntax against the given patterns, in order. If a pattern matches, return the result of evaluating the associated exp.

Compare the following definitions of when:

(define-syntax when
  (syntax-rules ()
    ((_ test e e* ...)
     (if test (begin e e* ...)))))

(define-syntax when
  (lambda (x)
    (syntax-case x ()
      ((_ test e e* ...)
       #'(if test (begin e e* ...))))))

Clearly, the syntax-case definition is similar to its syntax-rules counterpart, and equally clearly there are some differences. The syntax-case definition is wrapped in a lambda, a function of one argument; that argument is passed to the syntax-case invocation; and the “return value” of the macro has a #' prefix.

All of these differences stem from the fact that syntax-case does not define a syntax transformer itself – instead, syntax-case expressions provide a way to destructure a syntax object, and to rebuild syntax objects as output.

So the lambda wrapper is simply a leaky implementation detail, that syntax transformers are just functions that transform syntax to syntax. This should not be surprising, given that we have already described macros as “programs that write programs”. syntax-case is simply a way to take apart and put together program text, and to be a valid syntax transformer it needs to be wrapped in a procedure.

Unlike traditional Lisp macros (see Lisp-style Macro Definitions), syntax-case macros transform syntax objects, not raw Scheme forms. Recall the naive expansion of my-or given in the previous section:

(let ((t #t))
  (my-or #f t))
;; naive expansion:
(let ((t #t))
  (let ((t #f))
    (if t t t)))

Raw Scheme forms simply don’t have enough information to distinguish the first two t instances in (if t t t) from the third t. So instead of representing identifiers as symbols, the syntax expander represents identifiers as annotated syntax objects, attaching such information to those syntax objects as is needed to maintain referential transparency.

Syntax: syntax form

Create a syntax object wrapping form within the current lexical context.

Syntax objects are typically created internally to the process of expansion, but it is possible to create them outside of syntax expansion:

(syntax (foo bar baz))
⇒ #<some representation of that syntax>

However it is more common, and useful, to create syntax objects when building output from a syntax-case expression.

(define-syntax add1
  (lambda (x)
    (syntax-case x ()
      ((_ exp)
       (syntax (+ exp 1))))))

It is not strictly necessary for a syntax-case expression to return a syntax object, because syntax-case expressions can be used in helper functions, or otherwise used outside of syntax expansion itself. However a syntax transformer procedure must return a syntax object, so most uses of syntax-case do end up returning syntax objects.

Here in this case, the form that built the return value was (syntax (+ exp 1)). The interesting thing about this is that within a syntax expression, any appearance of a pattern variable is substituted into the resulting syntax object, carrying with it all relevant metadata from the source expression, such as lexical identity and source location.

Indeed, a pattern variable may only be referenced from inside a syntax form. The syntax expander would raise an error when defining add1 if it found exp referenced outside a syntax form.

Since syntax appears frequently in macro-heavy code, it has a special reader macro: #'. #'foo is transformed by the reader into (syntax foo), just as 'foo is transformed into (quote foo).

The pattern language used by syntax-case is conveniently the same language used by syntax-rules. Given this, Guile actually defines syntax-rules in terms of syntax-case:

(define-syntax syntax-rules
  (lambda (x)
    (syntax-case x ()
      ((_ (k ...) ((keyword . pattern) template) ...)
       #'(lambda (x)
           (syntax-case x (k ...)
             ((dummy . pattern) #'template)
             ...))))))

And that’s that.

6.8.3.1 Why syntax-case?

The examples we have shown thus far could just as well have been expressed with syntax-rules, and have just shown that syntax-case is more verbose, which is true. But there is a difference: syntax-case creates procedural macros, giving the full power of Scheme to the macro expander. This has many practical applications.

A common desire is to be able to match a form only if it is an identifier. This is impossible with syntax-rules, given the datum matching forms. But with syntax-case it is easy:

Scheme Procedure: identifier? syntax-object

Returns #t if syntax-object is an identifier, or #f otherwise.

;; relying on previous add1 definition
(define-syntax add1!
  (lambda (x)
    (syntax-case x ()
      ((_ var) (identifier? #'var)
       #'(set! var (add1 var))))))

(define foo 0)
(add1! foo)
foo ⇒ 1
(add1! "not-an-identifier") ⇒ error

With syntax-rules, the error for (add1! "not-an-identifier") would be something like “invalid set!”. With syntax-case, it will say something like “invalid add1!”, because we attach the guard clause to the pattern: (identifier? #'var). This becomes more important with more complicated macros. It is necessary to use identifier?, because to the expander, an identifier is more than a bare symbol.

Note that even in the guard clause, we reference the var pattern variable within a syntax form, via #'var.

Another common desire is to introduce bindings into the lexical context of the output expression. One example would be in the so-called “anaphoric macros”, like aif. Anaphoric macros bind some expression to a well-known identifier, often it, within their bodies. For example, in (aif (foo) (bar it)), it would be bound to the result of (foo).

To begin with, we should mention a solution that doesn’t work:

;; doesn't work
(define-syntax aif
  (lambda (x)
    (syntax-case x ()
      ((_ test then else)
       #'(let ((it test))
           (if it then else))))))

The reason that this doesn’t work is that, by default, the expander will preserve referential transparency; the then and else expressions won’t have access to the binding of it.

But they can, if we explicitly introduce a binding via datum->syntax.

Scheme Procedure: datum->syntax template-id datum [#:source=#f]

Create a syntax object that wraps datum, within the lexical context corresponding to the identifier template-id. If template-id is false, the datum will have no lexical context information.

Syntax objects have an associated source location. Internally this is represented as a 3-element vector of filename, line, and column. Usually this location ultimately is provided by read-syntax; See Reading Scheme Code, For the Compiler.

If a syntax object is passed as source, the resulting syntax object will have the source location of source. Otherwise if source is a 3-element source location vector, that vector will be the source location of the resulting syntax object. If source is a source properties alist, those will be parsed and set as the source location of the resulting syntax object. Otherwise if source is false, the source properties are looked up from (source-properties datum). See Source Properties.

For completeness, we should mention that it is possible to strip the metadata from a syntax object, returning a raw Scheme datum:

Scheme Procedure: syntax->datum syntax-object

Strip the metadata from syntax-object, returning its contents as a raw Scheme datum.

In this case we want to introduce it in the context of the whole expression, so we can create a syntax object as (datum->syntax x 'it), where x is the whole expression, as passed to the transformer procedure.

Here’s another solution that doesn’t work:

;; doesn't work either
(define-syntax aif
  (lambda (x)
    (syntax-case x ()
      ((_ test then else)
       (let ((it (datum->syntax x 'it)))
         #'(let ((it test))
             (if it then else)))))))

The reason that this one doesn’t work is that there are really two environments at work here – the environment of pattern variables, as bound by syntax-case, and the environment of lexical variables, as bound by normal Scheme. The outer let form establishes a binding in the environment of lexical variables, but the inner let form is inside a syntax form, where only pattern variables will be substituted. Here we need to introduce a piece of the lexical environment into the pattern variable environment, and we can do so using syntax-case itself:

;; works, but is obtuse
(define-syntax aif
  (lambda (x)
    (syntax-case x ()
      ((_ test then else)
       ;; invoking syntax-case on the generated
       ;; syntax object to expose it to `syntax'
       (syntax-case (datum->syntax x 'it) ()
         (it
           #'(let ((it test))
               (if it then else))))))))

(aif (getuid) (display it) (display "none")) (newline)
-| 500

However there are easier ways to write this. with-syntax is often convenient:

Syntax: with-syntax ((pat val) …) exp …

Bind patterns pat from their corresponding values val, within the lexical context of exp ....

;; better
(define-syntax aif
  (lambda (x)
    (syntax-case x ()
      ((_ test then else)
       (with-syntax ((it (datum->syntax x 'it)))
         #'(let ((it test))
             (if it then else)))))))

As you might imagine, with-syntax is defined in terms of syntax-case. But even that might be off-putting to you if you are an old Lisp macro hacker, used to building macro output with quasiquote. The issue is that with-syntax creates a separation between the point of definition of a value and its point of substitution.

So for cases in which a quasiquote style makes more sense, syntax-case also defines quasisyntax, and the related unsyntax and unsyntax-splicing, abbreviated by the reader as #`, #,, and #,@, respectively.

For example, to define a macro that inserts a compile-time timestamp into a source file, one may write:

(define-syntax display-compile-timestamp
  (lambda (x)
    (syntax-case x ()
      ((_)
       #`(begin
          (display "The compile timestamp was: ")
          (display #,(current-time))
          (newline))))))

Readers interested in further information on syntax-case macros should see R. Kent Dybvig’s excellent The Scheme Programming Language, either edition 3 or 4, in the chapter on syntax. Dybvig was the primary author of the syntax-case system. The book itself is available online at http://scheme.com/tspl4/.

6.8.3.2 Custom Ellipsis Identifiers for syntax-case Macros

When writing procedural macros that generate macro definitions, it is convenient to use a different ellipsis identifier at each level. Guile supports this for procedural macros using the with-ellipsis special form:

Syntax: with-ellipsis ellipsis body …

ellipsis must be an identifier. Evaluate body in a special lexical environment such that all macro patterns and templates within body will use ellipsis as the ellipsis identifier instead of the usual three dots (...).

For example:

(define-syntax define-quotation-macros
  (lambda (x)
    (syntax-case x ()
      ((_ (macro-name head-symbol) ...)
       #'(begin (define-syntax macro-name
                  (lambda (x)
                    (with-ellipsis :::
                      (syntax-case x ()
                        ((_ x :::)
                         #'(quote (head-symbol x :::)))))))
                ...)))))
(define-quotation-macros (quote-a a) (quote-b b) (quote-c c))
(quote-a 1 2 3) ⇒ (a 1 2 3)

Note that with-ellipsis does not affect the ellipsis identifier of the generated code, unless with-ellipsis is included around the generated code.

6.8.3.3 Syntax objects can be data too

Generally speaking, you want the macro expander to pick apart all syntax objects in a source term. The source and scope annotations attached to the syntax object are of interest to how the macro expander computes the result, but no syntax object itself should appear in the expanded term—usually. Sometimes, though, a macro will want a syntax object to appear in the expanded output. Normally you would just use quote to introduce the syntax object as a value, but the expander strips syntax objects from subexpression of quote. For this rare use case, Guile has quote-syntax, which does not strip its subexpression.

Syntax: quote-syntax form

Expand to the syntax object form, as a constant literal. Like quote, but without calling syntax->datum.