11.2 Syntax Object Content

(syntax? v) → boolean?

v : any/c

Returns #t if v is a syntax object, #f otherwise. See also Syntax Objects.

(syntax-source stx) → any

stx : syntax?

Returns the source for the syntax object stx, or #f if none is known. The source is represented by an arbitrary value (e.g., one passed to 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 current-compile.

(syntax-line stx)   →   (or/c positive-exact-integer?       false/c)

stx : syntax?

Returns the line number (positive exact integer) for the start of the syntax object in its source, or #f if the line number or source is unknown. The result is #f if and only if (syntax-column stx) produces #f. See also Counting Positions, Lines, and Columns, and see syntax-source for information about marshaling compiled syntax objects.

(syntax-column stx)   →   (or/c exact-nonnegative-integer?       false/c)

stx : syntax?

Returns the column number (non-negative exact integer) for the start of the syntax object in its source, or #f if the source column is unknown. The result is #f if and only if (syntax-line stx) produces #f. See also Counting Positions, Lines, and Columns, and see syntax-source for information about marshaling compiled syntax objects.

(syntax-position stx)   →   (or/c positive-exact-integer?       false/c)

stx : syntax?

Returns the character position (positive exact integer) for the start of the syntax object in its source, or #f if the source position is unknown. See also Counting Positions, Lines, and Columns, and see syntax-source for information about marshaling compiled syntax objects.

(syntax-span stx)   →   (or/c exact-nonnegative-integer?       false/c)

stx : syntax?

Returns the span (non-negative exact integer) in characters of the syntax object in its source, or #f if the span is unknown. See also syntax-source for information about marshaling compiled syntax objects.

(syntax-original? stx) → boolean?

stx : syntax?

Returns #t if stx has the property that read-syntax and read-honu-syntax attach to the syntax objects that they generate (see Syntax Object Properties), and if stx’s lexical information does not indicate that the object was introduced by a syntax transformer (see Syntax Objects). The result is #f otherwise. This predicate can be used to distinguish syntax objects in an expanded expression that were directly present in the original expression, as opposed to syntax objects inserted by macros.

(syntax-source-module stx)

→ (or/c module-path-index? symbol? false/c)

stx : syntax?

Returns a module path index or symbol (see Compiled Modules and References) for the module whose source contains stx, or #f if stx has no source module.

(syntax-e stx) → any

stx : syntax?

Unwraps the immediate datum structure from a syntax object, leaving nested syntax structure (if any) in place. The result of (syntax-e (scheme stx)) is one of the following:

• a symbol

• a syntax pair (described below)

• the empty list

• an immutable vector containing syntax objects

• an immutable box containing syntax objects

• some other kind of datum – usually a number, boolean, or string

A syntax pair is a pair containing a syntax object as its first element, and either the empty list, a syntax pair, or a syntax object as its second element.

A syntax object that is the result of read-syntax reflects the use of delimited . in the input by creating a syntax object for every pair of parentheses in the source, and by creating a pair-valued syntax object only for parentheses in the source. See Reading Pairs and Lists for more information.

(syntax->list stx) → (or/c list? false/c)

stx : syntax?

Returns a list of syntax objects or #f. The result is a list of syntax objects when (syntax->datum stx) would produce a list. In other words, syntax pairs in (syntax-e stx) are flattened.

(syntax->datum stx) → any

stx : syntax?

Returns a datum by stripping the lexical information, source-location information, properties, and certificates from stx. Inside of pairs, (immutable) vectors, and (immutable) boxes, syntax objects are recursively stripped.

The stripping operation does not mutate stx; it creates new pairs, vectors, and boxes as needed to strip lexical and source-location information recursively.

(datum->syntax ctxt v srcloc [prop cert]) → 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

Converts the datum v to a syntax object. If 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. Syntax objects already in v are preserved as-is in the result. For any kind of value other than a pair, vector, box, or syntax object, conversion means wrapping the value with lexical information, source-location information, properties, and certificates.

Converted objects in v are given the lexical context information of ctxt and the source-location information of srcloc. If v is not already a syntax object, then the resulting immediate syntax object is given the properties (see Syntax Object Properties) of prop and the inactive certificates (see Syntax Certificates) of cert; if v is a pair, vector, or box, recursively converted values are not given properties or certificates.

Any of ctxt, srcloc, prop, or cert can be #f, in which case the resulting syntax has no lexical context, source information, new properties, and/or certificates.

If srcloc is not #f or a syntax object, it must be a list or vector of five elements:

(list source-name line column position span)

or (vector source-name line column position span)

where source-name-v is an arbitrary value for the source name; line is an integer for the source line, or #f; column is an integer for the source column, or #f; position is an integer for the source position, or #f; and span is an integer for the source span, or #f. The line and column values must both be numbers or both be #f, otherwise the exn:fail:contract exception is raised.

Graph structure is not preserved by the conversion of v to a syntax object. Instead, v is essentially unfolded into a tree. If v has a cycle through pairs, vectors, and boxes, then the exn:fail:contract exception is raised.

(identifier? v) → boolean?

v : any/c

Returns #t if v is a syntax object and (syntax-e stx) produces a symbol.

(generate-temporaries stx-pair) → (listof identifier?)

stx-pair : (or syntax? list?)

Returns a list of identifiers that are distinct from all other identifiers. The list contains as many identifiers as stx-pair contains elements. The stx-pair argument must be a syntax pair that can be flattened into a list. The elements of 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 gensyms), so the limitations described with current-compile do not apply.