3 Datum Pattern Matching

▼ |  | Syntax: Meta-Programming Helpers

1 | Parsing and Specifying Syntax
2 | Syntax Object Helpers
3 | Datum Pattern Matching
4 | Module-Processing Helpers
5 | Macro Transformer Helpers
6 | Reader Helpers
7 | Parsing for Bodies
8 | Unsafe for Clause Transforms
9 | Source Locations
10 | Preserving Source Locations
11 | Non-Module Compilation And Expansion
12 | Trusting Standard Recertifying Transformers
13 | Attaching Documentation to Exports
14 | Contracts for Macro Subexpressions
15 | Macro Testing
16 | Internal-Definition Context Helpers
| Index

On this page:

datum-case
datum
with-datum
define/ with-datum
quasidatum
undatum
undatum-splicing

9.2
Racket
top contents ← prev up next →

## 3 Datum Pattern Matching🔗ℹ

(require syntax/datum) | package: base

The syntax/datum library provides forms that implement the pattern and template language of syntax-case, but for matching and constructing datum values instead of syntax.

For most pattern-matching purposes, racket/match is a better choice than syntax/datum. The syntax/datum library is useful mainly for its template support (i.e., datum) and, to a lesser extent, its direct correspondence to syntax-case patterns.

> > syntax
> > (datum-case datum-expr (literal-id ...)
> > clause ...)
> syntax (datum template)

Like syntax-case and syntax, but datum-expr in datum-case should produce a datum (i.e., plain S-expression) instead of a syntax object to be matched in clauses, and datum similarly produces a datum. Pattern variables bound in each clause of datum-case (or syntax-case, see below) are accessible via datum instead of syntax. When a literal-id appears in a clause’s pattern, it matches the corresponding symbol (using eq?).

Using datum-case and datum is similar to converting the input to syntax-case using datum->syntax and then wrapping each use of syntax with syntax->datum, but datum-case and datum do not create intermediate syntax objects, and they do not destroy existing syntax objects within the S-expression structure of datum-expr.

Example:

> > (datum-case '(1 "x" -> y) (->)
> [(a ... -> b) (datum (b (+ a) ...))])
> '(y (+ 1) (+ "x"))

The datum form also cooperates with syntax pattern variables such as those bound by syntax-case and attributes bound by syntax-parse (see Pattern Variables and Attributes for more information about attributes). As one consequence, datum provides a convenient way of getting the list of syntax objects bound to a syntax pattern variable of depth 1. For example, the following expressions are equivalent, except that the datum version avoids creating and eliminating a superfluous syntax object wrapper:

> > (with-syntax ([(x ...) #'(a b c)])
> (syntax->list #'(x ...)))
> '(#<syntax:eval:3:0 a> #<syntax:eval:3:0 b> #<syntax:eval:3:0 c>)
> > (with-syntax ([(x ...) #'(a b c)])
> (datum (x ...)))
> '(#<syntax:eval:4:0 a> #<syntax:eval:4:0 b> #<syntax:eval:4:0 c>)

A template can also use multiple syntax or datum pattern variables and datum constants, and it can use the ~@ and ~? template forms:

> > (with-syntax ([(x ...) #'(a b c)])
> (with-datum ([(y ...) (list 1 2 3)])
> (datum ([x -> y] ...))))
> '((#<syntax:eval:5:0 a> -> 1)
> (#<syntax:eval:5:0 b> -> 2)
> (#<syntax:eval:5:0 c> -> 3))
> > (with-syntax ([(x ...) #'(a b c)])
> (with-datum ([(y ...) (list 1 2 3)])
> (datum ((~@ x y) ...))))
> '(#<syntax:eval:6:0 a> 1 #<syntax:eval:6:0 b> 2 #<syntax:eval:6:0 c> 3)

See Attributes and datum for examples of ~? with datum.

If a datum variable is used in a syntax template, a compile-time error is raised.

Changed in version 7.8.0.9 of package base: Changed datum to cooperate with syntax-case, syntax-parse, etc.

> > syntax
> > (with-datum ([pattern datum-expr] ...)
> > body ...+)

Analogous to with-syntax, but for datum-case and datum instead of syntax-case and syntax.

Example:

> > (with-datum ([(a ...) '(1 2 3)]
> [(b ...) '("x" "y" "z")])
> (datum ((a b) ...)))
> '((1 "x") (2 "y") (3 "z"))

> syntax (define/with-datum pattern datum-expr)

The definition form of with-datum. Analogous to define/with-syntax, but for datum-case and datum.

Examples:

> > (define/with-datum ((x y) ...)
> '((a 1) (b 2) (c 3)))
> > (datum ((x ...)
> (y ...)))
> '((a b c) (1 2 3))

Added in version 8.2.0.8 of package base.

> syntax (quasidatum template)
> syntax (undatum expr)
> syntax (undatum-splicing expr)

Analogous to quasisyntax, unsyntax, and unsyntax-splicing.

Example:

> > (with-datum ([(a ...) '(1 2 3)])
> (quasidatum ((undatum (- 1 1)) a ... (undatum (+ 2 2)))))
> '(0 1 2 3 4)

top contents ← prev up next →