12.2 Syntax Object Content

► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

▼ | 12 | Macros

12.1 | Pattern-Based Syntax Matching
12.2 | Syntax Object Content
12.3 | Syntax Object Bindings
12.4 | Syntax Transformers
12.5 | Syntax Parameters
12.6 | Local Binding with Splicing Body
12.7 | Syntax Object Properties
12.8 | Syntax Taints
12.9 | Expanding Top-Level Forms
12.10 | Serializing Syntax
12.11 | File Inclusion
12.12 | Syntax Utilities
12.13 | Phase and Space Utilities

► | 12.2 | Syntax Object Content

12.2.1 | Syntax Object Source Locations

On this page:

syntax?
identifier?
syntax-source
syntax-line
syntax-column
syntax-position
syntax-span
syntax-original?
syntax-source-module
syntax-e
syntax->list
syntax->datum
datum->syntax
syntax-binding-set?
syntax-binding-set
syntax-binding-set->syntax
syntax-binding-set-extend
datum-intern-literal
syntax-shift-phase-level
generate-temporaries
identifier-prune-lexical-context
identifier-prune-to-source-module
syntax-recertify
syntax-debug-info
12.2.1`` Syntax Object Source Locations
syntax-srcloc

top contents ← prev up next →

#### 12.2`` Syntax Object Content🔗ℹ

> procedure (syntax? v) → boolean?
> v : any/c

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

Examples:

> > (syntax? #'quinoa)
> #t
> > (syntax? #'(spelt triticale buckwheat))
> #t
> > (syntax? (datum->syntax #f 'millet))
> #t
> > (syntax? "barley")
> #f

> procedure (identifier? v) → boolean?
> v : any/c

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

Examples:

> > (identifier? #'linguine)
> #t
> > (identifier? #'(if wheat? udon soba))
> #f
> > (identifier? 'ramen)
> #f
> > (identifier? 15)
> #f

> procedure (syntax-source stx) → any/c
> stx : syntax?

Returns the source component of the source location 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.

See also syntax-srcloc from racket/syntax-srcloc.

> procedure (syntax-line stx) → (or/c exact-positive-integer? #f)
> stx : syntax?

Returns the line number (positive exact integer) of the source location for the start of the syntax object in its source, or #f if the line number or source is unknown. See also Counting Positions, Lines, and Columns.

Changed in version 7.0 of package base: Dropped a guarantee that syntax-line and syntax-column both produce #f or both produce integers.

> procedure (syntax-column stx) → (or/c exact-nonnegative-integer? #f)
> stx : syntax?

Returns the column number (non-negative exact integer) of the source location for the start of the syntax object in its source, or #f if the source column is unknown. See also Counting Positions, Lines, and Columns.

Changed in version 7.0 of package base: Dropped a guarantee that syntax-line and syntax-column both produce #f or both produce integers.

> procedure (syntax-position stx) → (or/c exact-positive-integer? #f)
> stx : syntax?

Returns the position (positive exact integer) of the source location for the start of the syntax object in its source, or #f if the source position is unknown. The position is intended to be a character position, but reading from a port without line counting enabled will produce a position as a byte offset. See also Counting Positions, Lines, and Columns.

> procedure (syntax-span stx) → (or/c exact-nonnegative-integer? #f)
> stx : syntax?

Returns the span (non-negative exact integer) of the source location for syntax object in its source, or #f if the span is unknown. The span is intended to count in characters, but reading from a port without line counting enabled will produce a span in bytes. See also Counting Positions, Lines, and Columns.

> procedure (syntax-original? stx) → boolean?
> stx : syntax?

Returns #t if stx has the property that read-syntax attaches to the syntax objects that they generate (see Syntax Object Properties), and if stx’s lexical information does not include any macro-introduction scopes (which 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.

The (hidden) property to represent original syntax is dropped for a syntax object that is marshaled as part of compiled code; see also current-compile.

> procedure (syntax-source-module stx [source?])
> → (or/c module-path-index? symbol? path? resolved-module-path? #f)
> stx : syntax?
> source? : any/c = #f

Returns an indication of the module whose source contains stx, or #f if no source module for stx can be inferred from its lexical context. If source? is #f, then result is a module path index or symbol (see Compiled Modules and References) or a resolved module path; if source? is true, the result is a path or symbol corresponding to the loaded module’s source in the sense of current-module-declare-source.

Note that syntax-source-module does not consult the source location of stx. The result is based on the lexical information of stx.

> procedure (syntax-e stx) → any/c
> stx : syntax?

Unwraps the immediate datum structure from a syntax object, leaving nested syntax structure (if any) in place. The result of (syntax-e 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

- an immutable hash table containing syntax object values (but not necessarily syntax object keys)

- an immutable prefab structure containing syntax objects

- some other kind of datum—usually a number, boolean, or string—that is interned when datum-intern-literal would convert the value

Examples:

> > (syntax-e #'a)
> 'a
> > (syntax-e #'(x . y))
> '(#<syntax:eval:11:0 x> . #<syntax:eval:11:0 y>)
> > (syntax-e #'#(1 2 (+ 3 4)))
> '#(#<syntax:eval:12:0 1> #<syntax:eval:12:0 2> #<syntax:eval:12:0 (+ 3 4)>)
> > (syntax-e #'#&"hello world")
> '#&#<syntax:eval:13:0 "hello world">
> > (syntax-e #'#hash((imperial . "yellow") (festival . "green")))
> '#hash((festival . #<syntax:eval:14:0 "green">)
> (imperial . #<syntax:eval:14:0 "yellow">))
> > (syntax-e #'#(point 3 4))
> '#(#<syntax:eval:15:0 point> #<syntax:eval:15:0 3> #<syntax:eval:15:0 4>)
> > (syntax-e #'3)
> 3
> > (syntax-e #'"three")
> "three"
> > (syntax-e #'#t)
> #t

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.

If stx is tainted, then any syntax object in the result of (syntax-e stx) is tainted. The results from multiple calls to syntax-e of stx are eq?.

> procedure (syntax->list stx) → (or/c list? #f)
> 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.

If stx is tainted, then any syntax object in the result of (syntax->list stx) is tainted.

Examples:

> > (syntax->list #'())
> '()
> > (syntax->list #'(1 (+ 3 4) 5 6))
> '(#<syntax:eval:20:0 1>
> #<syntax:eval:20:0 (+ 3 4)>
> #<syntax:eval:20:0 5>
> #<syntax:eval:20:0 6>)
> > (syntax->list #'a)
> #f

> procedure (syntax->datum stx) → any/c
> stx : syntax?

Returns a datum by stripping the lexical information, source-location information, properties, and tamper status from stx. Inside of pairs, (immutable) vectors, (immutable) boxes, immutable hash table values (not keys), and immutable prefab structures, syntax objects are recursively stripped.

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

Examples:

> > (syntax->datum #'a)
> 'a
> > (syntax->datum #'(x . y))
> '(x . y)
> > (syntax->datum #'#(1 2 (+ 3 4)))
> '#(1 2 (+ 3 4))
> > (syntax->datum #'#&"hello world")
> '#&"hello world"
> > (syntax->datum #'#hash((imperial . "yellow") (festival . "green")))
> '#hash((festival . "green") (imperial . "yellow"))
> > (syntax->datum #'#(point 3 4))
> '#(point 3 4)
> > (syntax->datum #'3)
> 3
> > (syntax->datum #'"three")
> "three"
> > (syntax->datum #'#t)
> #t

> procedure (datum->syntax ctxt v [srcloc prop ignored]) → syntax?
> ctxt : (or/c syntax? #f)
> v : any/c
> | srcloc |  | : |  |
> (or/c #f
> syntax?
> srcloc?
> (list/c any/c
> (or/c exact-positive-integer? #f)
> (or/c exact-nonnegative-integer? #f)
> (or/c exact-positive-integer? #f)
> (or/c exact-nonnegative-integer? #f))
> (vector/c any/c
> (or/c exact-positive-integer? #f)
> (or/c exact-nonnegative-integer? #f)
> (or/c exact-positive-integer? #f)
> (or/c exact-nonnegative-integer? #f)))
> |  |  | = |  | #f
> prop : (or/c syntax? #f) = #f
> ignored : (or/c syntax? #f) = #f

Converts the datum v to a syntax object. If v is already a syntax object, then there is no conversion, and v is returned unmodified. The contents of pairs, vectors, and boxes, the fields of prefab structures, and the values of immutable hash tables are recursively converted. The keys of prefab structures and the keys of immutable hash tables are not converted. Mutable vectors and boxes are replaced by immutable vectors and boxes. For any kind of value other than a pair, vector, box, immutable hash table, immutable prefab structure, or syntax object, conversion means wrapping the value with lexical information, source-location information, and properties after the value is interned via datum-intern-literal.

Converted objects in v are given the lexical context information of ctxt and the source-location information of srcloc. The resulting immediate syntax object from conversion is given the properties (see Syntax Object Properties) of prop (even the hidden ones that would not be visible via syntax-property-symbol-keys); if v is a pair, vector, box, immutable hash table, or immutable prefab structure, recursively converted values are not given properties. If ctxt is tainted, then the resulting syntax object from datum->syntax is tainted. The code inspector of ctxt, if any, is compared to the code inspector of the module for the macro currently being transformed, if any; if both inspectors are available and if one is the same as or inferior to the other, then the result syntax has the same/inferior inspector, otherwise it has no code inspector.

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

If srcloc is not #f, a srcloc instance, or a syntax object, it must be a list or vector of five elements that correspond to srcloc fields.

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, boxes, immutable hash tables, and immutable prefab structures, then the exn:fail:contract exception is raised.

The ignored argument is allowed for backward compatibility and has no effect on the returned syntax object.

Changed in version 8.2.0.5 of package base: Allow a srcloc value as a srcloc argument.

> procedure (syntax-binding-set? v) → boolean?
> v : any/c
> procedure (syntax-binding-set) → syntax-binding-set?
> > procedure
> > (syntax-binding-set->syntax |  | binding-set |  |  |  |
> > |  | datum) |  | → |  | syntax?
> binding-set : syntax-binding-set?
> datum : any/c
> > procedure
> > (syntax-binding-set-extend |
> > |  | binding-set |
> > |  | symbol |
> > |  | phase |
> > |  | mpi |
> > | [ | #:source-symbol source-symbol |
> > |  | #:source-phase source-phase |
> > |  | #:nominal-module nominal-mpi |
> > |  | #:nominal-phase nominal-phase |
> > |  | #:nominal-symbol nominal-symbol |
> > |  | #:nominal-require-phase nominal-require-phase |
> > |  | #:inspector inspector]) |
> → syntax-binding-set?
> binding-set : syntax-binding-set?
> symbol : symbol?
> phase : (or/c exact-integer? #f)
> mpi : module-path-index?
> source-symbol : symbol? = symbol
> source-phase : (or/c exact-integer? #f) = phase
> nominal-mpi : module-path-index? = mpi
> nominal-phase : (or/c exact-integer? #f) = source-phase
> nominal-symbol : symbol? = source-symbol
> nominal-require-phase : (or/c exact-integer? #f) = 0
> inspector : (or/c inspector? #f) = #f

A syntax binding set supports explicit construction of binding information for a syntax object. Start by creating an empty binding set with syntax-binding-set, add bindings with syntax-binding-set-extend, and create a syntax object that has the bindings as its lexical information using syntax-binding-set->syntax.

The first three arguments to syntax-binding-set-extend establish a binding of symbol at phase to an identifier that is defined in the module referenced by mpi. Supply source-symbol to make the binding of symbol refer to a different provided variable from mpi, and so on; the optional arguments correspond to the results of identifier-binding.

Added in version 7.0.0.12 of package base.

> procedure (datum-intern-literal v) → any/c
> v : any/c

Converts some values to be consistent with an interned result produced by the default reader in read-syntax mode.

If v is a number, character, string, byte string, or regular expression, then the result is a value that is equal? to v and eq? to a potential result of the default reader. (Note that mutable strings and byte strings are interned as immutable strings and byte strings.)

If v is an uninterned or an unreadable symbol, the result is still v, since an interned symbol would not be equal? to v.

The conversion process does not traverse compound values. For example, if v is a pair containing strings, then the strings within v are not interned.

If v1 and v2 are equal? but not eq?, then it is possible that (datum-intern-literal v1) will return v1 and—sometime after v1 becomes unreachable as determined by the garbage collector (see Garbage Collection)—(datum-intern-literal v2) can still return v2. In other words, datum-intern-literal may adopt a given value as an interned representative, but if a former representative becomes otherwise unreachable, then datum-intern-literal may adopt a new representative.

> procedure (syntax-shift-phase-level stx shift) → syntax?
> stx : syntax?
> shift : (or/c exact-integer? #f)

Returns a syntax object that is like stx, but with all of its top-level and module bindings shifted by shift phase levels. If shift is #f, then only bindings at phase level 0 are shifted to the label phase level. If shift is 0, then the result is stx.

> procedure (generate-temporaries v) → (listof identifier?)
> v : stx-list?

Returns a list of identifiers that are distinct from all other identifiers. The list contains as many identifiers as v contains elements. The elements of v 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); see also Printing Compiled Code.

Examples:

> > (generate-temporaries '(a b c d))
> '(#<syntax a1> #<syntax b2> #<syntax c3> #<syntax d4>)
> > (generate-temporaries #'(1 2 3 4))
> '(#<syntax temp5> #<syntax temp6> #<syntax temp7> #<syntax temp8>)
> > (define-syntax (set!-values stx)
> (syntax-case stx ()
> [(_ (id ...) expr)
> (with-syntax ([(temp ...) (generate-temporaries #'(id ...))])
> #'(let-values ([(temp ...) expr])
> (set! id temp) ... (void)))]))

> > procedure
> > (identifier-prune-lexical-context |  | id-stx |  |  |  |
> > | [ | syms]) |  | → |  | identifier?
> id-stx : identifier?
> syms : (listof symbol?) = (list (syntax-e id-stx))

Returns an identifier with the same binding as id-stx, but without possibly lexical information from id-stx that does not apply to the symbols in syms, where even further extension of the lexical information drops information for other symbols. In particular, transferring the lexical context via datum->syntax from the result of this function to a symbol other than one in syms may produce an identifier with no binding.

Currently, the result is always id-stx exactly. Pruning was intended primarily as a kind of optimization in a previous version of Racket, but it is less useful and difficult to implement efficiently in the current macro expander.

See also quote-syntax/prune.

Changed in version 6.5 of package base: Always return id-stx.

> procedure (identifier-prune-to-source-module id-stx) → identifier?
> id-stx : identifier?

Returns an identifier with its lexical context minimized to that needed for syntax-source-module. The minimized lexical context does not include any bindings.

> > procedure
> > (syntax-recertify |  | new-stx |  |  |  |
> > |  | old-stx |  |  |  |
> > |  | inspector |  |  |  |
> > |  | key) |  | → |  | syntax?
> new-stx : syntax?
> old-stx : syntax?
> inspector : inspector?
> key : any/c

For backward compatibility only; returns new-stx.

> procedure (syntax-debug-info stx [phase all-bindings?]) → hash?
> stx : syntax?
> phase : (or/c exact-integer? #f) = (syntax-local-phase-level)
> all-bindings? : any/c = #f

Produces a hash table that describes the lexical information of stx (not counting components when (syntax-e stx) would return a compound value). The result can include—but is not limited to—the following keys:

- 'name — the result of (syntax-e stx), if it is a symbol.

- 'context — a list of vectors, where each vector represents a scope attached to stx.

  Each vector starts with a number that is distinct for every scope. A symbol afterward provides a hint at the scope’s origin: 'module for a module scope, 'macro for a macro-introduction scope, 'use-site for a macro use-site scope, or 'local for a local binding form. In the case of a 'module scope that corresponds to the inside edge, the module’s name and a phase (since an inside-edge scope is generated for each phase) are shown.

- 'bindings — a list of bindings, each represented by a hash table. A binding table can include—but is not limited to—the following keys:

  - 'name — the symbolic name for the binding.

  - 'context — the scopes, as a list of vectors, for the binding.

  - 'local — a symbol representing a local binding; when this key is present, 'module is absent.

  - 'module — an encoding of a import from another module; when this key is present, 'local is absent.

  - 'free-identifier=? — a hash table of debugging information from an identifier for which the binding is an alias.

- 'fallbacks — a list of hash tables like the one produced by syntax-debug-info for cross-namespace binding fallbacks.

Added in version 6.3 of package base.

##### 12.2.1`` Syntax Object Source Locations🔗ℹ

(require racket/syntax-srcloc) | package: base

The bindings documented in this section are provided by the racket/syntax-srcloc library, not racket/base or racket.

> procedure (syntax-srcloc stx) → (or/c #f srcloc?)
> stx : syntax?

Returns the source location for the syntax object stx, or #f if none is known.

Added in version 8.2.0.5 of package base.

top contents ← prev up next →