{"size": 4593, "ext": "scrbl", "max_stars_repo_path": "share/pkgs/racket-doc/syntax/scribblings/datum.scrbl", "max_stars_repo_name": "takikawa/racket-ppa", "max_stars_repo_stars_event_min_datetime": "2018-07-29T04:13:52.000Z", "max_stars_repo_stars_event_max_datetime": "2022-02-14T16:11:17.000Z", "max_issues_repo_path": "share/pkgs/racket-doc/syntax/scribblings/datum.scrbl", "max_issues_repo_name": "takikawa/racket-ppa", "max_issues_repo_issues_event_min_datetime": "2017-08-25T20:26:37.000Z", "max_issues_repo_issues_event_max_datetime": "2022-02-26T17:48:40.000Z", "max_forks_repo_path": "share/pkgs/racket-doc/syntax/scribblings/datum.scrbl", "max_forks_repo_name": "takikawa/racket-ppa", "max_forks_repo_forks_event_min_datetime": null, "max_forks_repo_forks_event_max_datetime": null}
{"max_stars_count": 10, "max_issues_count": 15, "max_forks_count": null, "avg_line_length": 32.1188811189, "max_line_length": 76, "alphanum_fraction": 0.677988243}
#lang scribble/manual
@(require "common.rkt"
          scribble/eval
          (for-label racket/base
                     racket/syntax
                     syntax/datum
                     syntax/parse))

@(define datum-eval (make-base-eval))
@interaction-eval[#:eval datum-eval (require syntax/datum)]

@title{Datum Pattern Matching}

@defmodule[syntax/datum]{The @racketmodname[syntax/datum] library
provides forms that implement the pattern and template language of
@racket[syntax-case], but for matching and constructing datum values
instead of syntax.}

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


@deftogether[(
@defform[(datum-case datum-expr (literal-id ...)
           clause ...)]
@defform[(datum template)]
)]{

Like @racket[syntax-case] and @racket[syntax], but @racket[datum-expr]
in @racket[datum-case] should produce a @tech[#:doc refman]{datum}
(i.e., plain S-expression) instead of a @tech[#:doc refman]{syntax
object} to be matched in @racket[clause]s, and @racket[datum]
similarly produces a datum.  Pattern variables bound in each
@racket[clause] of @racket[datum-case] (or @racket[syntax-case], see
below) are accessible via @racket[datum] instead of
@racket[syntax]. When a @racket[literal-id] appears in a
@racket[clause]'s pattern, it matches the corresponding symbol (using
@racket[eq?]).

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

@examples[
#:eval datum-eval
(datum-case '(1 "x" -> y) (->)
  [(a ... -> b) (datum (b (+ a) ...))])
]

The @racket[datum] form also cooperates with @tech[#:key "pattern
variable" #:doc '(lib "scribblings/reference/reference.scrbl")]{syntax
pattern variables} such as those bound by @racket[syntax-case] and
@tech{attributes} bound by @racket[syntax-parse] (see
@secref["stxparse-attrs"] for more information about attributes). As
one consequence, @racket[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 @racket[datum] version avoids creating and eliminating a
superfluous syntax object wrapper:

@interaction[#:eval datum-eval
(with-syntax ([(x ...) #'(a b c)])
  (syntax->list #'(x ...)))
(with-syntax ([(x ...) #'(a b c)])
  (datum (x ...)))
]

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

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

See @secref["attributes-and-datum"] for examples of @racket[~?] with
@racket[datum].

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

@history[#:changed "7.8.0.9" @elem{Changed @racket[datum] to
cooperate with @racket[syntax-case], @racket[syntax-parse], etc.}]}


@defform[(with-datum ([pattern datum-expr] ...)
           body ...+)]{

Analogous to @racket[with-syntax], but for @racket[datum-case] and
@racket[datum] instead of @racket[syntax-case] and @racket[syntax].

@examples[
#:eval datum-eval
(with-datum ([(a ...) '(1 2 3)]
             [(b ...) '("x" "y" "z")])
  (datum ((a b) ...)))
]}

@defform[(define/with-datum pattern datum-expr)]{

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

@examples[
#:eval datum-eval
 (define/with-datum ((x y) ...)
   '((a 1) (b 2) (c 3)))
 (datum ((x ...)
         (y ...)))
]

@history[#:added "8.2.0.8"]}

@deftogether[(
@defform[(quasidatum template)]
@defform[(undatum expr)]
@defform[(undatum-splicing expr)]
)]{

Analogous to @racket[quasisyntax], @racket[unsyntax], and
@racket[unsyntax-splicing].

@examples[
#:eval datum-eval
(with-datum ([(a ...) '(1 2 3)])
  (quasidatum ((undatum (- 1 1)) a ... (undatum (+ 2 2)))))
]}


@close-eval[datum-eval]
