244 lines
9.2 KiB
Racket
244 lines
9.2 KiB
Racket
#lang scribble/doc
|
|
@(require "mz.ss"
|
|
(for-label scheme/stxparam
|
|
scheme/stxparam-exptime))
|
|
|
|
@title[#:tag "stxcmp"]{Syntax Object Bindings}
|
|
|
|
@defproc[(bound-identifier=? [a-id syntax?][b-id syntax?]) boolean?]{
|
|
|
|
Returns @scheme[#t] if the identifier @scheme[a-id] would bind
|
|
@scheme[b-id] (or vice-versa) if the identifiers were substituted in a
|
|
suitable expression context, @scheme[#f] otherwise.}
|
|
|
|
|
|
@defproc[(free-identifier=? [a-id syntax?][b-id syntax?]) boolean?]{
|
|
|
|
Returns @scheme[#t] if @scheme[a-id] and @scheme[b-id] access the same
|
|
lexical, module, or top-level binding at @tech{phase level} 0. ``Same
|
|
module binding'' means that the identifiers refer to the same original
|
|
definition site, not necessarily the @scheme[require] or
|
|
@scheme[provide] site. Due to renaming in @scheme[require] and
|
|
@scheme[provide], the identifiers may return distinct results with
|
|
@scheme[syntax-e].}
|
|
|
|
|
|
@defproc[(free-transformer-identifier=? [a-id syntax?][b-id syntax?]) boolean?]{
|
|
|
|
Returns @scheme[#t] if @scheme[a-id] and @scheme[b-id] access the same
|
|
lexical, module, or top-level binding at @tech{phase level} 1 (see
|
|
@secref["id-model"]).}
|
|
|
|
|
|
@defproc[(free-template-identifier=? [a-id syntax?][b-id syntax?]) boolean?]{
|
|
|
|
Returns @scheme[#t] if @scheme[a-id] and @scheme[b-id] access the same
|
|
lexical or module binding at @tech{phase level} -1 (see
|
|
@secref["id-model"]).}
|
|
|
|
|
|
@defproc[(free-label-identifier=? [a-id syntax?][b-id syntax?]) boolean?]{
|
|
|
|
Returns @scheme[#t] if @scheme[a-id] and @scheme[b-id] access the same
|
|
lexical or module binding at the @tech{label phase level} (see
|
|
@secref["id-model"]).}
|
|
|
|
|
|
@defproc[(check-duplicate-identifier [ids (listof identifier?)])
|
|
(or/c identifier? false/c)]{
|
|
|
|
Compares each identifier in @scheme[ids] with every other identifier
|
|
in the list with @scheme[bound-identifier=?]. If any comparison
|
|
returns @scheme[#t], one of the duplicate identifiers is returned (the
|
|
first one in @scheme[ids] that is a duplicate), otherwise the result
|
|
is @scheme[#f].}
|
|
|
|
|
|
@defproc[(identifier-binding [id-stx syntax?])
|
|
(or/c (one-of 'lexical #f)
|
|
(listof (or/c module-path-index? symbol?)
|
|
symbol?
|
|
(or/c module-path-index? symbol?)
|
|
symbol?
|
|
boolean?))]{
|
|
|
|
Returns one of three kinds of values, depending on the binding of
|
|
@scheme[id-stx] at @tech{phase level} 0:
|
|
|
|
@itemize{
|
|
|
|
@item{The result is @indexed-scheme['lexical] if @scheme[id-stx]
|
|
has a @tech{local binding}.}
|
|
|
|
@item{The result is a list of five items when @scheme[id-stx]
|
|
has a @tech{module binding}: @scheme[(list source-mod source-id
|
|
nominal-source-mod nominal-source-id et?)].
|
|
|
|
@itemize{
|
|
|
|
@item{@scheme[source-mod] is a module path index (see
|
|
@secref["modpathidx"]) that indicates the defining module.}
|
|
|
|
@item{@scheme[source-id] is a symbol for the identifier's name
|
|
at its definition site in the source module. This can be
|
|
different from the local name returned by
|
|
@scheme[syntax->datum] for several reasons: the identifier is
|
|
renamed on import, it is renamed on export, or it is
|
|
implicitly renamed because the identifier (or its import) was
|
|
generated by a macro invocation.}
|
|
|
|
@item{@scheme[nominal-source-mod] is a module path index (see
|
|
@secref["modpathidx"]) that indicates the module
|
|
@scheme[require]d into the context of @scheme[id-stx] to
|
|
provide its binding. It can be different from
|
|
@scheme[source-mod] due to a re-export in
|
|
@scheme[nominal-source-mod] of some imported identifier.}
|
|
|
|
@item{@scheme[nominal-source-id] is a symbol for the
|
|
identifier's name as exported by
|
|
@scheme[nominal-source-mod]. It can be different from
|
|
@scheme[source-id] due to a renaming @scheme[provide], even if
|
|
@scheme[source-mod] and @scheme[nominal-source-mod] are the
|
|
same.}
|
|
|
|
@item{@scheme[et?] is @scheme[#t] if the source definition is
|
|
for-syntax, @scheme[#f] otherwise.}
|
|
|
|
}}
|
|
|
|
@item{The result is @scheme[#f] if @scheme[id-stx]
|
|
has a @tech{top-level binding}.}
|
|
|
|
}}
|
|
|
|
@defproc[(identifier-transformer-binding [id-stx syntax?])
|
|
(or/c (one-of 'lexical #f)
|
|
(listof (or/c module-path-index? symbol?)
|
|
symbol?
|
|
(or/c module-path-index? symbol?)
|
|
symbol?
|
|
boolean?))]{
|
|
|
|
Like @scheme[identifier-binding], but that the reported information is
|
|
for the identifier's binding in @tech{phase level} 1 (see
|
|
@secref["id-model"]).
|
|
|
|
If the result is @scheme['lexical] for either of
|
|
@scheme[identifier-binding] or
|
|
@scheme[identifier-transformer-binding], then the result is always
|
|
@scheme['lexical] for both.}
|
|
|
|
|
|
@defproc[(identifier-template-binding [id-stx syntax?])
|
|
(or/c (one-of 'lexical #f)
|
|
(listof (or/c module-path-index? symbol?)
|
|
symbol?
|
|
(or/c module-path-index? symbol?)
|
|
symbol?
|
|
boolean?))]{
|
|
|
|
Like @scheme[identifier-binding], but that the reported information is
|
|
for the identifier's binding in @tech{phase level} -1 (see
|
|
@secref["id-model"]).
|
|
|
|
If the result is @scheme['lexical] for either of
|
|
@scheme[identifier-binding] or
|
|
@scheme[identifier-template-binding], then the result is always
|
|
@scheme['lexical] for both.}
|
|
|
|
|
|
@defproc[(identifier-label-binding [id-stx syntax?])
|
|
(or/c false/c
|
|
(listof (or/c module-path-index? symbol?)
|
|
symbol?
|
|
(or/c module-path-index? symbol?)
|
|
symbol?
|
|
boolean?))]{
|
|
|
|
Like @scheme[identifier-binding], but that the reported information is
|
|
for the identifier's binding in the @tech{label phase level} (see
|
|
@secref["id-model"]).
|
|
|
|
Unlike @scheme[identifier-binding], the result cannot be
|
|
@scheme['lexical].}
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@section[#:tag "stxparam"]{Syntax Parameters}
|
|
|
|
@note-lib-only[scheme/stxparam]
|
|
|
|
@defform[(define-syntax-parameter id expr)]{
|
|
|
|
Binds @scheme[id] as syntax to a @deftech{syntax
|
|
parameter}. The @scheme[expr] is an expression in the
|
|
@tech{transformer environment} that serves as the default value for
|
|
the @tech{syntax parameter}. The value is typically obtained by a transformer
|
|
using @scheme[syntax-parameter-value].
|
|
|
|
The @scheme[id] can be used with @scheme[syntax-parameterize]
|
|
or @scheme[syntax-parameter-value] (in a transformer). If
|
|
@scheme[expr] produces a procedure of one argument or a
|
|
@scheme[make-set!-transformer] result, then @scheme[id] can be
|
|
used as a macro. If @scheme[expr] produces a
|
|
@scheme[rename-transformer] result, then @scheme[id] can be
|
|
used as a macro that expands to a use of the target identifier, but
|
|
@scheme[syntax-local-value] of @scheme[id] does not produce
|
|
the target's value.}
|
|
|
|
@defform[(syntax-parameterize ((id expr) ...) body-expr ...+)]{
|
|
|
|
Each @scheme[id] must be bound to a @tech{syntax parameter} using
|
|
@scheme[define-syntax-parameter]. Each @scheme[expr] is an expression
|
|
in the @tech{transformer environment}. During the expansion of the
|
|
@scheme[body-expr]s, the value of each @scheme[expr] is bound to the
|
|
corresponding @scheme[id].
|
|
|
|
If an @scheme[expr] produces a procedure of one argument or a
|
|
@scheme[make-set!-transformer] result, then its @scheme[id]
|
|
can be used as a macro during the expansion of the
|
|
@scheme[body-expr]s. If @scheme[expr] produces a
|
|
@scheme[rename-transformer] result, then @scheme[id] can be
|
|
used as a macro that expands to a use of the target identifier, but
|
|
@scheme[syntax-local-value] of @scheme[id] does not produce
|
|
the target's value.}
|
|
|
|
|
|
@defproc[(syntax-parameter-value [id-stx syntax?]) any]{
|
|
|
|
This procedure is intended for use in a @tech{transformer
|
|
environment}, where @scheme[id-stx] is an identifier bound in the
|
|
normal environment to a @tech{syntax parameter}. The result is the current
|
|
value of the @tech{syntax parameter}, as adjusted by
|
|
@scheme[syntax-parameterize] form.
|
|
|
|
This binding is provided @scheme[for-syntax] by
|
|
@schememodname[scheme/stxparam], since it is normally used in a
|
|
transformer. It is provided normally by
|
|
@scheme[scheme/stxparam-exptime].}
|
|
|
|
|
|
@defproc[(make-parameter-rename-transformer [id-stx syntax?]) any]{
|
|
|
|
This procedure is intended for use in a transformer, where
|
|
@scheme[id-stx] is an identifier bound to a @tech{syntax parameter}. The
|
|
result is transformer that behaves as @scheme[id-stx], but that cannot
|
|
be used with @scheme[syntax-parameterize] or
|
|
@scheme[syntax-parameter-value].
|
|
|
|
Using @scheme[make-parameter-rename-transformer] is analogous to
|
|
defining a procedure that calls a parameter. Such a procedure can be
|
|
exported to others to allow access to the parameter value, but not to
|
|
change the parameter value. Similarly,
|
|
@scheme[make-parameter-rename-transformer] allows a @tech{syntax parameter}
|
|
to used as a macro, but not changed.
|
|
|
|
The result of @scheme[make-parameter-rename-transformer] is not
|
|
treated specially by @scheme[syntax-local-value], unlike the result
|
|
of @scheme[make-rename-transformer].
|
|
|
|
This binding is provided @scheme[for-syntax] by
|
|
@schememodname[scheme/stxparam], since it is normally used in a
|
|
transformer. It is provided normally by
|
|
@scheme[scheme/stxparam-exptime].}
|