12.2 Syntax Object Content

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.

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

• 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

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 or armed, then any syntax object in the result of (syntax-e stx) is tainted, and multiple calls to syntax-e may return values that are not eq?. For a stx that is not armed, the results from multiple calls to syntax-e of stx are eq?.

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

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.

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 or armed, 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 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 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, 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.

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.

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.

The generated identifiers are built with interned symbols (not gensyms); see also Printing Compiled Code.

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.

• '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.