On this page:
1.11.1 Contracts for Macro Sub-expressions
1.11.2 Contracts for Syntax Classes
provide-syntax-class/  contract
syntax-class/  c
1.11.3 Reflection
reify-syntax-class
reified-syntax-class?
reified-splicing-syntax-class?
reified-syntax-class-attributes
reified-syntax-class-arity
reified-syntax-class-keywords
reified-syntax-class-curry
1.11.4 Procedural Splicing Syntax Classes
define-primitive-splicing-syntax-class
1.11.5 Ellipsis-head Alternative Sets
define-eh-alternative-set
1.11.6 Syntax Class Specialization
define-syntax-class/  specialize
1.11.7 Syntax Templates
template
??
?@
define-template-metafunction
template/  loc
quasitemplate
quasitemplate/  loc
datum-template

1.11 Experimental

The following facilities are experimental.

1.11.1 Contracts for Macro Sub-expressions

 (require syntax/parse/experimental/contract)
  package: base

This module is deprecated; it reprovides expr/c for backward compatibility.

1.11.2 Contracts for Syntax Classes

 (require syntax/parse/experimental/provide)
  package: base

syntax

(provide-syntax-class/contract
  [syntax-class-id syntax-class-contract] ...)
 
syntax-class-contract = (syntax-class/c (mandatory-arg ...))
  | 
(syntax-class/c (mandatory-arg ...)
                (optional-arg ...))
     
arg = contract-expr
  | keyword contract-expr
 
  contract-expr : contract?
Provides the syntax class (or splicing syntax class) syntax-class-id with the given contracts imposed on its formal parameters.

Keyword recognized by provide-syntax-class/contract.

1.11.3 Reflection

 (require syntax/parse/experimental/reflect)
  package: base

A syntax class can be reified into a run-time value, and a reified syntax class can be used in a pattern via the ~reflect and ~splicing-reflect pattern forms.

syntax

(reify-syntax-class syntax-class-id)

Reifies the syntax class named syntax-class-id as a run-time value. The same form also handles splicing syntax classes. Syntax classes with the #:no-delimit-cut option cannot be reified.

procedure

(reified-syntax-class? x)  boolean?

  x : any/c

procedure

(reified-splicing-syntax-class? x)  boolean?

  x : any/c
Returns #t if x is a reified (normal) syntax class or a reified splicing syntax class, respectively.

Returns the reified syntax class’s attributes.

Returns the reified syntax class’s arity and keywords, respectively. Compare with procedure-arity and procedure-keywords.

procedure

(reified-syntax-class-curry r 
  arg ... 
  #:<kw> kw-arg ...) 
  (or/c reified-syntax-class? reified-splicing-syntax-class?)
  r : (or/c reified-syntax-class? reified-splicing-syntax-class?)
  arg : any/c
  kw-arg : any/c
Partially applies the reified syntax class to the given arguments. If more arguments are given than the reified syntax class accepts, an error is raised.

  S-pattern = ....
  | (~reflect var-id (reified-expr arg-expr ...) maybe-attrs)
     
  H-pattern = ....
  | 
(~splicing-reflect var-id (reified-expr arg-expr ...)
                   maybe-attrs)

(~reflect var-id (reified-expr arg-expr ...) maybe-attrs)
 
maybe-attrs = 
  | #:attributes (attr-arity-decl ...)

Like ~var, except that the syntax class position is an expression evaluating to a reified syntax object, not a syntax class name, and the attributes bound by the reified syntax class (if any) must be specified explicitly.

(~splicing-reflect var-id (reified-expr arg-expr ...) maybe-attrs)

Like ~reflect but for reified splicing syntax classes.

Examples:
> (define-syntax-class (nat> x)
    #:description (format "natural number greater than ~s" x)
    #:attributes (diff)
    (pattern n:nat
             #:when (> (syntax-e #'n) x)
             #:with diff (- (syntax-e #'n) x)))
> (define-syntax-class (nat/mult x)
    #:description (format "natural number multiple of ~s" x)
    #:attributes (quot)
    (pattern n:nat
             #:when (zero? (remainder (syntax-e #'n) x))
             #:with quot (quotient (syntax-e #'n) x)))
> (define r-nat> (reify-syntax-class nat>))
> (define r-nat/mult (reify-syntax-class nat/mult))
> (define (partition/r stx r n)
    (syntax-parse stx
      [((~alt (~reflect yes (r n)) no) ...)
       #'((yes ...) (no ...))]))
> (partition/r #'(1 2 3 4 5) r-nat> 3)

#<syntax:5:0 ((4 5) (1 2 3))>

> (partition/r #'(1 2 3 4 5) r-nat/mult 2)

#<syntax:5:0 ((2 4) (1 3 5))>

> (define (bad-attrs r)
    (syntax-parse #'6
      [(~reflect x (r 3) #:attributes (diff))
       #'x.diff]))
> (bad-attrs r-nat>)

#<syntax 3>

> (bad-attrs r-nat/mult)

reflect-syntax-class: reified syntax-class is missing

declared attribute `diff'

1.11.4 Procedural Splicing Syntax Classes

 (require syntax/parse/experimental/splicing)
  package: base

syntax

(define-primitive-splicing-syntax-class (name-id param-id ...)
  maybe-description maybe-attrs
  parser-expr)
 
  parser : 
(-> syntax?
    (->* () ((or/c string? #f) -> any))
    (cons/c exact-positive-integer? list?))
Defines a splicing syntax via a procedural parser.

The parser procedure is given two arguments, the syntax to parse and a failure procedure. To signal a successful parse, the parser procedure returns a list of N+1 elements, where N is the number of attributes declared by the splicing syntax class. The first element is the size of the prefix consumed. The rest of the list contains the values of the attributes.

To indicate failure, the parser calls the failure procedure with an optional message argument.

1.11.5 Ellipsis-head Alternative Sets

 (require syntax/parse/experimental/eh) package: base

Unlike single-term patterns and head patterns, ellipsis-head patterns cannot be encapsulated by syntax classes, since they describe not only sets of terms but also repetition constraints.

This module provides ellipsis-head alternative sets, reusable encapsulations of ellipsis-head patterns.

syntax

(define-eh-alternative-set name eh-alternative ...)

 
alternative = (pattern EH-pattern)
Defines name as an ellipsis-head alternative set. Using name (via ~eh-var) in an ellipsis-head pattern is equivalent to including each of the alternatives in the pattern via ~alt, except that the attributes bound by the alternatives are prefixed with the name given to ~eh-var.

Unlike syntax classes, ellipsis-head alternative sets must be defined before they are referenced.

  EH-pattern = ....
  | (~eh-var name eh-alternative-set-id)

(~eh-var name eh-alternative-set-id)

Includes the alternatives of eh-alternative-set-id, prefixing their attributes with name.

Examples:
> (define-eh-alternative-set options
    (pattern (~once (~seq #:a a:expr) #:name "#:a option"))
    (pattern (~seq #:b b:expr)))
> (define (parse/options stx)
    (syntax-parse stx
      [(_ (~eh-var s options) ...)
       #'(s.a (s.b ...))]))
> (parse/options #'(m #:a 1 #:b 2 #:b 3))

#<syntax:12:0 (1 (2 3))>

> (parse/options #'(m #:a 1 #:a 2))

m: too many occurrences of #:a option

  at: ()

  within: (m #:a 1 #:a 2)

  in: (m #:a 1 #:a 2)

> (define (parse/more-options stx)
    (syntax-parse stx
      [(_ (~alt (~eh-var s options)
                (~seq #:c c1:expr c2:expr))
          ...)
       #'(s.a (s.b ...) ((c1 c2) ...))]))
> (parse/more-options #'(m #:a 1 #:b 2 #:c 3 4 #:c 5 6))

#<syntax:15:0 (1 (2) ((3 4) (5 6)))>

> (define-eh-alternative-set ext-options
    (pattern (~eh-var s options))
    (pattern (~seq #:c c1 c2)))
> (syntax-parse #'(m #:a 1 #:b 2 #:c 3 4 #:c 5 6)
    [(_ (~eh-var x ext-options) ...)
     #'(x.s.a (x.s.b ...) ((x.c1 x.c2) ...))])

#<syntax:18:0 (1 (2) ((3 4) (5 6)))>

1.11.6 Syntax Class Specialization

 (require syntax/parse/experimental/specialize)
  package: base

syntax

(define-syntax-class/specialize header syntax-class-use)

 
header = id
  | (id . kw-formals)
     
syntax-class-use = target-stxclass-id
  | (target-stxclass-id arg ...)
Defines id as a syntax class with the same attributes, options (eg, #:commit, #:no-delimit-cut), and patterns as target-stxclass-id but with the given args supplied.

Examples:
> (define-syntax-class/specialize nat>10 (nat> 10))
> (syntax-parse #'(11 12) [(n:nat>10 ...) 'ok])

'ok

> (syntax-parse #'(8 9) [(n:nat>10 ...) 'ok])

?: expected natural number greater than 10

  at: 8

  in: (8 9)

1.11.7 Syntax Templates

 (require syntax/parse/experimental/template)
  package: base

syntax

(template tmpl)

 
tmpl = pattern-variable-id
  | (head-tmpl . tmpl)
  | (head-tmpl ellipsis ...+ . tmpl)
  | (metafunction-id . tmpl)
  | (?? tmpl tmpl)
  | #(head-tmpl ...)
  | #s(prefab-struct-key head-tmpl ...)
  | #&tmpl
  | constant-term
     
head-templ = tmpl
  | (?? head-tmpl)
  | (?? head-tmpl head-tmpl)
  | (?@ . tmpl)
     
ellipsis = ...
Constructs a syntax object from a syntax template, like syntax, but provides additional templating forms for dealing with optional terms and splicing sequences of terms. Only the additional forms are described here; see syntax for descriptions of pattern variables, etc.

As in syntax, a template can be “escaped” with ellipses, like (... escaped-tmpl). Within the escaped template, ellipses (...), the ?? and ?@ forms, and metafunctions are treated as constants rather than interpreted as template forms.

(?? tmpl alt-tmpl)

Produces tmpl unless any attribute used in tmpl has an absent value; in that case, alt-tmpl is used instead.

Examples:
> (syntax-parse #'(m 1 2 3)
    [(_ (~optional (~seq #:op op:expr)) arg:expr ...)
     (template ((?? op +) arg ...))])

#<syntax:22:0 (+ 1 2 3)>

> (syntax-parse #'(m #:op max 1 2 3)
    [(_ (~optional (~seq #:op op:expr)) arg:expr ...)
     (template ((?? op +) arg ...))])

#<syntax:23:0 (max 1 2 3)>

If ?? is used as a head-template, then its sub-templates may also be head-templates.

Examples:
> (syntax-parse #'(m 1)
    [(_ x:expr (~optional y:expr))
     (template (m2 x (?? (?@ #:y y) (?@ #:z 0))))])

#<syntax:24:0 (m2 1 #:z 0)>

> (syntax-parse #'(m 1 2)
    [(_ x:expr (~optional y:expr))
     (template (m2 x (?? (?@ #:y y) (?@ #:z 0))))])

#<syntax:25:0 (m2 1 #:y 2)>

(?? head-tmpl)

Produces head-tmpl unless any attribute used in head-tmpl has an absent value; in that case, the term is omitted. Can only occur in head position in a template.

Equivalent to (?? head-tmpl (?@)).

Examples:
> (syntax-parse #'(m 1)
    [(_ x:expr (~optional y:expr))
     (template (m2 x (?? y)))])

#<syntax:26:0 (m2 1)>

> (syntax-parse #'(m 1 2)
    [(_ x:expr (~optional y:expr))
     (template (m2 x (?? y)))])

#<syntax:27:0 (m2 1 2)>

> (syntax-parse #'(m 1 2)
    [(_ x:expr (~optional y:expr))
     (template (m2 x (?? (?@ #:y y))))])

#<syntax:28:0 (m2 1 #:y 2)>

(?@ . tmpl)

Similar to unquote-splicing, splices the result of tmpl (which must produce a syntax list) into the surrounding template. Can only occur in head position in a template.

Example:
> (syntax-parse #'(m #:a 1 #:b 2 3 4 #:e 5)
    [(_ (~alt pos:expr (~seq kw:keyword kwarg:expr)) ...)
     (template (m2 (?@ kw kwarg) ... pos ...))])

#<syntax:29:0 (m2 #:a 1 #:b 2 #:e 5 3 4)>

The tmpl must produce a proper syntax list, but it does not need to be expressed as a proper list. For example, to unpack pattern variables that contain syntax lists, use a “dotted” template:

Examples:
> (with-syntax ([x #'(a b c)])
    (template ((?@ . x) d)))

#<syntax:30:0 (a b c d)>

> (with-syntax ([(x ...) #'((1 2 3) (4 5))])
    (template ((?@ . x) ...)))

#<syntax:31:0 (1 2 3 4 5)>

(metafunction-id . tmpl)

Applies the template metafunction named metafunction-id to the result of the template (including metafunction-id itself). See define-template-metafunction for examples.

The ?? and ?@ forms and metafunction applications are disabled in an “escaped template” (see stat-template under syntax).

Example:
> (template (... ((?@ a b c) d)))

#<syntax:32:0 ((?@ a b c) d)>

syntax

??

syntax

?@

Auxiliary forms used by template. They may not be used as expressions.

syntax

(define-template-metafunction metafunction-id expr)

(define-template-metafunction (metafunction-id . formals) body ...+)
Defines metafunction-id as a template metafunction. A metafunction application in a template expression (but not a syntax expression) is evaluated by applying the metafunction to the result of processing the “argument” part of the template.

Examples:
> (define-template-metafunction (join stx)
    (syntax-parse stx
      [(join (~optional (~seq #:lctx lctx)) a:id b:id ...)
       (datum->syntax (or (attribute lctx) #'a)
                      (string->symbol
                       (apply string-append
                              (map symbol->string
                                   (syntax->datum #'(a b ...)))))
                      stx)]))
> (template (join a b c))

#<syntax:34:0 abc>

> (with-syntax ([(x ...) #'(a b c)])
    (template ((x (join tmp- x)) ...)))

#<syntax:35:0 ((a tmp-a) (b tmp-b) (c tmp-c))>

Metafunctions are useful for performing transformations in contexts where macro expansion does not occur, such as binding occurrences. For example:

> (syntax->datum
   (with-syntax ([name #'posn]
                 [(field ...) #'(x y)])
     (template (let-values ([((join name ?)
                              (join #:lctx name make- name)
                              (join name - field) ...)
                             (make-struct-type __)])
                 __))))

'(let-values (((posn? make-posn posn-x posn-y) (make-struct-type __))) __)

If join were defined as a macro, it would not be usable in the context above; instead, let-values would report an invalid binding list.

syntax

(template/loc loc-expr tmpl)

syntax

(quasitemplate tmpl)

syntax

(quasitemplate/loc loc-expr tmpl)

Like syntax/loc, quasisyntax, and quasisyntax/loc, respectively, but with the additional features of template.

syntax

(datum-template tmpl)

Like datum but with some of the additional features of template: ?@ and ?? are supported (although ?? is useless, since datum-case cannot bind “absent” variables), but template metafunctions are not allowed.