220 lines
9.1 KiB
Racket
220 lines
9.1 KiB
Racket
#lang scribble/doc
|
|
@(require "mz.ss")
|
|
|
|
@title[#:tag "stxops"]{Syntax Object Content}
|
|
|
|
@defproc[(syntax? [v any/c]) boolean?]{
|
|
|
|
Returns @scheme[#t] if @scheme[v] is a @tech{syntax object}, @scheme[#f]
|
|
otherwise. See also @secref["stxobj-model"].}
|
|
|
|
@defproc[(syntax-source [stx syntax?]) any]{
|
|
|
|
Returns the source for the @tech{syntax object} @scheme[stx], or @scheme[#f]
|
|
if none is known. The source is represented by an arbitrary value
|
|
(e.g., one passed to @scheme[read-syntax]), but it is typically a file
|
|
path string. Source-location information is dropped for a syntax
|
|
object that is marshaled as part of compiled code; see also
|
|
@scheme[current-compile].}
|
|
|
|
|
|
@defproc[(syntax-line [stx syntax?])
|
|
(or/c positive-exact-integer?
|
|
false/c)]{
|
|
|
|
Returns the line number (positive exact integer) for the start of the
|
|
@tech{syntax object} in its source, or @scheme[#f] if the line number or
|
|
source is unknown. The result is @scheme[#f] if and only if
|
|
@scheme[(syntax-column stx)] produces @scheme[#f]. See also
|
|
@secref["linecol"], and see @scheme[syntax-source] for information
|
|
about marshaling compiled @tech{syntax object}s.}
|
|
|
|
|
|
@defproc[(syntax-column [stx syntax?])
|
|
(or/c exact-nonnegative-integer?
|
|
false/c)]{
|
|
|
|
Returns the column number (non-negative exact integer) for the start
|
|
of the @tech{syntax object} in its source, or @scheme[#f] if the source
|
|
column is unknown. The result is @scheme[#f] if and only if
|
|
@scheme[(syntax-line stx)] produces @scheme[#f]. See also
|
|
@secref["linecol"], and see @scheme[syntax-source] for information
|
|
about marshaling compiled @tech{syntax object}s.}
|
|
|
|
|
|
@defproc[(syntax-position [stx syntax?])
|
|
(or/c positive-exact-integer?
|
|
false/c)]{
|
|
|
|
Returns the character position (positive exact integer) for the start
|
|
of the @tech{syntax object} in its source, or @scheme[#f] if the source
|
|
position is unknown. See also @secref["linecol"], and see
|
|
@scheme[syntax-source] for information about marshaling compiled
|
|
@tech{syntax object}s.}
|
|
|
|
|
|
@defproc[(syntax-span [stx syntax?])
|
|
(or/c exact-nonnegative-integer?
|
|
false/c)]{
|
|
|
|
Returns the span (non-negative exact integer) in characters of the
|
|
@tech{syntax object} in its source, or @scheme[#f] if the span is
|
|
unknown. See also @scheme[syntax-source] for information about
|
|
marshaling compiled @tech{syntax object}s.}
|
|
|
|
|
|
@defproc[(syntax-original? [stx syntax?]) boolean?]{
|
|
|
|
Returns @scheme[#t] if @scheme[stx] has the property that
|
|
@scheme[read-syntax] and @scheme[read-honu-syntax] attach to the
|
|
@tech{syntax object}s that they generate (see @secref["stxprops"]), and if
|
|
@scheme[stx]'s @tech{lexical information} does not indicate that the
|
|
object was introduced by a syntax transformer (see
|
|
@secref["stxobj-model"]). The result is @scheme[#f] otherwise. This
|
|
predicate can be used to distinguish @tech{syntax object}s in an expanded
|
|
expression that were directly present in the original expression, as
|
|
opposed to @tech{syntax object}s inserted by macros.}
|
|
|
|
|
|
@defproc[(syntax-source-module [stx syntax?])
|
|
(or/c module-path-index? symbol? false/c)]{
|
|
|
|
Returns a module path index or symbol (see @secref["modpathidx"])
|
|
for the module whose source contains @scheme[stx], or @scheme[#f] if
|
|
@scheme[stx] has no source module.}
|
|
|
|
|
|
@defproc[(syntax-e [stx syntax?]) any]{
|
|
|
|
Unwraps the immediate datum structure from a @tech{syntax object},
|
|
leaving nested syntax structure (if any) in place. The result of
|
|
@scheme[(syntax-e @scheme[stx])] is one of the following:
|
|
|
|
@itemize{
|
|
|
|
@item{a symbol}
|
|
|
|
@item{a @tech{syntax pair} (described below)}
|
|
|
|
@item{the empty list}
|
|
|
|
@item{an immutable vector containing @tech{syntax object}s}
|
|
|
|
@item{an immutable box containing @tech{syntax object}s}
|
|
|
|
@item{some other kind of datum---usually a number, boolean, or string}
|
|
|
|
}
|
|
|
|
A @deftech{syntax pair} is a pair containing a @tech{syntax object} as its
|
|
first element, and either the empty list, a syntax pair, or a syntax
|
|
object as its second element.
|
|
|
|
A @tech{syntax object} that is the result of @scheme[read-syntax] reflects
|
|
the use of delimited @litchar{.} in the input by creating a syntax
|
|
object for every pair of parentheses in the source, and by creating a
|
|
pair-valued @tech{syntax object} @italic{only} for parentheses in the
|
|
source. See @secref["parse-pair"] for more information.}
|
|
|
|
|
|
@defproc[(syntax->list [stx syntax?])
|
|
(or/c list? false/c)]{
|
|
|
|
Returns a list of @tech{syntax object}s or @scheme[#f]. The result is a list
|
|
of @tech{syntax object}s when @scheme[(syntax->datum stx)] would produce a
|
|
list. In other words, @tech{syntax pairs} in @scheme[(syntax-e stx)]
|
|
are flattened.}
|
|
|
|
|
|
@defproc[(syntax->datum [stx syntax?]) any]{
|
|
|
|
Returns a datum by stripping the lexical information, source-location
|
|
information, properties, and certificates from @scheme[stx]. Inside of
|
|
pairs, (immutable) vectors, and (immutable) boxes, @tech{syntax object}s are
|
|
recursively stripped.
|
|
|
|
The stripping operation does not mutate @scheme[stx]; it creates new
|
|
pairs, vectors, and boxes as needed to strip lexical and
|
|
source-location information recursively.}
|
|
|
|
@defproc[(datum->syntax [ctxt (or/c syntax? false/c)]
|
|
[v any/c]
|
|
[srcloc (or/c syntax? false/c
|
|
(list/c any/c
|
|
(or/c exact-positive-integer? false/c)
|
|
(or/c exact-nonnegative-integer? false/c)
|
|
(or/c exact-nonnegative-integer? false/c)
|
|
(or/c exact-positive-integer? false/c))
|
|
(vector/c any/c
|
|
(or/c exact-positive-integer? false/c)
|
|
(or/c exact-nonnegative-integer? false/c)
|
|
(or/c exact-nonnegative-integer? false/c)
|
|
(or/c exact-positive-integer? false/c)))]
|
|
[prop (or/c syntax? false/c) #f]
|
|
[cert (or/c syntax? false/c) #f])
|
|
syntax?]{
|
|
|
|
Converts the @tech{datum} @scheme[v] to a @tech{syntax object}. If
|
|
@scheme[v] is a pair, vector, or box, then the contents are
|
|
recursively converted; mutable vectors and boxes are essentially
|
|
replaced by immutable vectors and boxes. @tech{Syntax object}s already in
|
|
@scheme[v] are preserved as-is in the result. For any kind of value
|
|
other than a pair, vector, box, or @tech{syntax object}, conversion means
|
|
wrapping the value with lexical information, source-location
|
|
information, properties, and certificates.
|
|
|
|
Converted objects in @scheme[v] are given the lexical context
|
|
information of @scheme[ctxt] and the source-location information of
|
|
@scheme[srcloc]. If @scheme[v] is not already a @tech{syntax object}, then
|
|
the resulting immediate @tech{syntax object} is given the properties (see
|
|
@secref["stxprops"]) of @scheme[prop] and the @tech{inactive
|
|
certificates} (see @secref["stxcerts"]) of @scheme[cert]; if
|
|
@scheme[v] is a pair, vector, or box, recursively converted values are
|
|
not given properties or certificates.
|
|
|
|
Any of @scheme[ctxt], @scheme[srcloc], @scheme[prop], or @scheme[cert]
|
|
can be @scheme[#f], in which case the resulting syntax has no lexical
|
|
context, source information, new properties, and/or certificates.
|
|
|
|
If @scheme[srcloc] is not @scheme[#f] or a @tech{syntax object}, it
|
|
must be a list or vector of five elements:
|
|
|
|
@schemeblock[
|
|
(list source-name line column position span)
|
|
#, @elem{or} (vector source-name line column position span)
|
|
]
|
|
|
|
where @scheme[source-name-v] is an arbitrary value for the source
|
|
name; @scheme[line] is an integer for the source line, or @scheme[#f];
|
|
@scheme[column] is an integer for the source column, or @scheme[#f];
|
|
@scheme[position] is an integer for the source position, or
|
|
@scheme[#f]; and @scheme[span] is an integer for the source span, or
|
|
@scheme[#f]. The @scheme[line] and @scheme[column] values must both be
|
|
numbers or both be @scheme[#f], otherwise the
|
|
@exnraise[exn:fail:contract].
|
|
|
|
Graph structure is not preserved by the conversion of @scheme[v] to a
|
|
@tech{syntax object}. Instead, @scheme[v] is essentially unfolded into a
|
|
tree. If @scheme[v] has a cycle through pairs, vectors, and boxes,
|
|
then the @exnraise[exn:fail:contract].}
|
|
|
|
@defproc[(identifier? [v any/c]) boolean?]{
|
|
|
|
Returns @scheme[#t] if @scheme[v] is a @tech{syntax object} and
|
|
@scheme[(syntax-e stx)] produces a symbol.}
|
|
|
|
|
|
@defproc[(generate-temporaries [stx-pair (or syntax? list?)])
|
|
(listof identifier?)]{
|
|
|
|
Returns a list of identifiers that are distinct from all other
|
|
identifiers. The list contains as many identifiers as
|
|
@scheme[stx-pair] contains elements. The @scheme[stx-pair] argument
|
|
must be a syntax pair that can be flattened into a list. The elements
|
|
of @scheme[stx-pair] can be anything, but string, symbol, keyword
|
|
(possibly wrapped as syntax), and identifier elements will be embedded
|
|
in the corresponding generated name, which is useful for debugging
|
|
purposes. The generated identifiers are built with interned symbols
|
|
(not @scheme[gensym]s), so the limitations described with
|
|
@scheme[current-compile] do not apply.}
|