#lang scribble/doc
@(require scribble/manual
          scribble/eval
          "planet.ss"
          "eval.ss")
@(require (for-label scheme "../syntax.ss"))

@title[#:style 'quiet #:tag "syntax"]{Syntax Objects}

@defmodule/this-package[syntax]

This module provides tools for macro transformers.

@section{Contracts}

@defproc[(syntax-datum/c [datum/c any/c]) flat-contract?]{

Recognizes syntax objects @scheme[stx] such that @scheme[(syntax->datum stx)]
satisfies @scheme[datum/c].

}

@defproc[(syntax-listof/c [elem/c any/c]) flat-contract?]{

Recognizes syntax objects @scheme[stx] such that @scheme[(syntax->list stx)]
satisfies @scheme[(listof elem/c)].

}

@defproc[(syntax-list/c [elem/c any/c] ...) flat-contract?]{

Recognizes syntax objects @scheme[stx] such that @scheme[(syntax->list stx)]
satisfies @scheme[(list/c elem/c ...)].

}

@section{Syntax Lists}

@defproc[(syntax-map [f (-> syntax? A)] [stx syntax?]) (listof A)]{

Performs @scheme[(map f (syntax->list stx))].

@defexamples[
#:eval (evaluator)
(syntax-map syntax-e #'(a (b c) d))
]

}

@section{Syntax Conversions}

@defproc[(to-syntax [datum any/c]
                    [#:stx stx (or/c false/c syntax?) #f]
                    [#:src src (or/c false/c syntax?) stx]
                    [#:ctxt ctxt (or/c false/c syntax?) stx]
                    [#:prop prop (or/c false/c syntax?) stx]
                    [#:cert cert (or/c false/c syntax?) stx])
         syntax?]{

A wrapper for @scheme[datum->syntax] with keyword arguments.

The "master" keyword @scheme[#:stx] sets all attributes from a single syntax
object, defaulting to @scheme[#f] for unadorned syntax objects.

The individual keywords @scheme[#:src], @scheme[#:ctxt], @scheme[#:prop], and
@scheme[#:cert] override @scheme[#:stx] for individual syntax object
attributes.  They control source location information, lexical context
information, syntax object properties, and syntax certificates, respectively.

@defexamples[
#:eval (evaluator)
(define blank-stx (to-syntax 'car))
blank-stx
(syntax-e blank-stx)
(free-identifier=? blank-stx #'car)
(define full-stx (to-syntax 'car #:stx #'here))
full-stx
(syntax-e full-stx)
(free-identifier=? full-stx #'car)
(define partial-stx (to-syntax 'car #:ctxt #'here))
partial-stx
(syntax-e partial-stx)
(free-identifier=? partial-stx #'car)
]

}

@defproc[(to-datum [x any/c]) (not/c syntax?)]{

A wrapper for @scheme[syntax->datum].  Produces @scheme[(syntax->datum x)] if
@scheme[x] is a syntax object and @scheme[x] otherwise.

@defexamples[
#:eval (evaluator)
(to-datum #'(a b c))
(to-datum (list #'a #'b #'c))
]

}

@section{Syntax Errors}

@defthing[current-syntax (parameter/c (or/c syntax? false/c))]{
A parameter that may be used to store the current syntax object being
transformed.  It is not used by the expander; you have to assign to it yourself.
This parameter is used by @scheme[syntax-error], below.  It defaults to
@scheme[#f].
}

@defproc[(syntax-error [stx syntax?] [fmt string?] [arg any/c] ...) none/c]{
Raises a syntax error based on the locations of @scheme[(current-syntax)] and
@scheme[stx], with @scheme[(format fmt arg ...)] as its message.
@defexamples[
#:eval (evaluator)
(define stx #'(a b c))
(parameterize ([current-syntax #f])
  (syntax-error stx "~s location" 'general))
(parameterize ([current-syntax stx])
  (syntax-error (car (syntax-e stx)) "~s location" 'specific))
]
}

@section{Pattern Bindings}

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

Like @scheme[with-syntax], but with nested scope.

@defexamples[
#:eval (evaluator)
(with-syntax* ([a #'id] [b #'a]) (syntax-e #'b))
]

}