11.4 Syntax Transformers

Example:

> (let ([x 1]         [y 2])     (let-syntax ([x (make-set!-transformer                       (lambda (stx)                         (syntax-case stx (set!)                           ; Redirect mutation of x to y                           [(set! id v) #'(set! y v)]                           ; Normal use of x really gets x                           [id (identifier? #'id)  #'x])))])       (begin         (set! x 3)         (list x y)))) '(1 3)

The property value must be an exact integer or procedure of one or two arguments. In the former case, the integer designates a field within the structure that should contain a procedure; the integer must be between 0 (inclusive) and the number of non-automatic fields in the structure type (exclusive, not counting supertype fields), and the designated field must also be specified as immutable.

If the property value is a procedure of one argument, then the procedure serves as a syntax transformer and for set! transformations. If the property value is a procedure of two arguments, then the first argument is the structure whose type has prop:set!-transformer property, and the second argument is a syntax object as for a syntax transformer and for set! transformations; set!-transformer-procedure applied to the structure produces a new function that accepts just the syntax object and calls the procedure associated through the property. Finally, if the property value is an integer, the target identifier is extracted from the structure instance; if the field value is not a procedure of one argument, then a procedure that always calls raise-syntax-error is used, instead.

If a value has both the prop:set!-transformer and prop:rename-transformer properties, then the latter takes precedence. If a structure type has the prop:set!-transformer and prop:procedure properties, then the former takes precedence for the purposes of macro expansion.

Such a transformer could be written manually, but the one created by make-rename-transformer triggers special cooperation with the parser and other syntactic forms when id is bound to the rename transformer:

• The parser to installs a free-identifier=? and identifier-binding equivalence between id and id-stx, as long as id-stx does not have a true value for the 'not-free-identifier=? syntax property.

• A provide of id provides the binding indicated by id-stx instead of id, as long as id-stx does not have a true value for the 'not-free-identifier=? syntax property and as long as id-stx has a binding.

• If provide exports id, it uses a symbol-valued 'nominal-id property of id-stx to specify the “nominal source identifier” of the binding as reported by identifier-binding.

• If id-stx has a true value for the 'not-provide-all-defined syntax property, then id (or its target) is not exported by all-defined-out.

• The syntax-local-value and syntax-local-make-delta-introducer functions recognize rename-transformer bindings and consult their targets.

The property value must be an exact integer or an identifier syntax object. In the former case, the integer designates a field within the structure that should contain an identifier; the integer must be between 0 (inclusive) and the number of non-automatic fields in the structure type (exclusive, not counting supertype fields), and the designated field must also be specified as immutable.

If the property value is an identifier, the identifier serves as the target for renaming, just like the first argument to make-rename-transformer. If the property value is an integer, the target identifier is extracted from the structure instance; if the field value is not an identifier, then an identifier ? with an empty context is used, instead.

When an identifier in stop-ids is encountered by the expander in a sub-expression, expansions stops for the sub-expression. If stop-ids is a non-empty list, then begin, quote, set!, lambda, case-lambda, let-values, letrec-values, if, begin0, with-continuation-mark, letrec-syntaxes+values, #%app, #%expression, #%top, and #%variable-reference are added to stop-ids. If #%app, #%top, or #%datum appears in stop-ids, then application, top-level variable reference, and literal data expressions without the respective explicit form are not wrapped with the explicit form. If stop-ids is #f instead of a list, then stx is expanded only as long as the outermost form of stx is a macro (i.e., expansion does not proceed to sub-expressions). A fully expanded form can include the bindings listed in Fully Expanded Programs plus the letrec-syntaxes+values form.

The optional intdef-ctx argument must be either #f, the result of syntax-local-make-definition-context, or a list of such results. In the latter two cases, lexical information for internal definitions is added to stx before it is expanded (in reverse order relative to the list). The lexical information is also added to the expansion result (because the expansion might introduce bindings or references to internal-definition bindings).

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

Examples:

> (define-syntax do-print     (syntax-rules ()       [(_ x ...) (printf x ...)])) > (define-syntax hello     (syntax-rules ()       [(_ x) (do-print "hello ~a" x)])) > (define-syntax (show stx)     (syntax-case stx ()       [(_ x)        (with-syntax ([partly-expanded (local-expand #'(hello x)                                                     'expression                                                     (list #'do-print))]                      [expanded (local-expand #'(hello x)                                              'expression                                              #f)])          (printf "partly expanded syntax is ~a\n" (syntax->datum #'partly-expanded))          (printf "expanded syntax is ~a\n" (syntax->datum #'expanded))          #'expanded)])) > (show 1) partly expanded syntax is (do-print hello ~a 1) expanded syntax is (printf hello ~a 1) hello 1

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

If intdef-ctx is not #f, then the new internal-definition context extends the given one. That is, expanding in the new internal-definition context can use bindings previously introduced into intdef-ctx.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

If simply removing the contexts produces a different binding than completely ignoring the contexts (due to nested internal definition contexts, for example), then the resulting identifier is given a syntax mark to simulate a non-existent lexical context. The intdef-ctx argument can be a list because removing internal-definition contexts one at a time can produce a different intermediate binding than removing them all at once.

If id-stx is bound to a rename transformer created with make-rename-transformer, syntax-local-value effectively calls itself with the target of the rename and returns that result, instead of the rename transformer.

If id-stx has no transformer binding (via define-syntax, let-syntax, etc.) in that environment, the result is obtained by applying failure-thunk if not #f. If failure-thunk is false, the exn:fail:contract exception is raised.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

If id-stx has no transformer binding, then failure-thunk is called (and it can return any number of values), or an exception is raised if failure-thunk is #f.

A run-time expression within a module is lifted to the module’s top level, just before the expression whose expansion requests the lift. Similarly, a run-time expression outside of a module is lifted to a top-level definition. A compile-time expression in a letrec-syntaxes+values or define-syntaxes binding is lifted to a let wrapper around the corresponding right-hand side of the binding. A compile-time expression within begin-for-syntax is lifted to a define-for-syntax declaration just before the requesting expression.

Other syntactic forms can capture lifts by using local-expand/capture-lifts or local-transformer-expand/capture-lifts.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

The resulting syntax object is the same as stx, except that a fresh syntax mark is added. The same syntax mark is added to the lifted #%require form, so that the #%require form can bind uses of imported identifiers in the resulting syntax object (assuming that the lexical information of stx includes the binding environment into which the #%require is lifted).

If raw-require-spec and stx are part of the input to a transformer, then typically syntax-local-introduce should be applied to each before passing them to syntax-local-lift-require, and then syntax-local-introduce should be applied to the result of syntax-local-lift-require. Otherwise, marks added by the macro expander can prevent access to the new imports.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

The symbol results indicate that the expression is being expanded for an expression context, a top-level context, a module context, or a module-begin context.

A list result indicates expansion in an internal-definition context. The identity of the list’s first element (i.e., its eq?ness) reflects the identity of the internal-definition context; in particular two transformer expansions receive the same first value if and only if they are invoked for the same internal-definition context. Later values in the list similarly identify internal-definition contexts that are still being expanded, and that required the expansion of nested internal-definition contexts.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

If a binding of inner-identifier shadows id-stx, the result is the same as (syntax-local-get-shadower inner-identifier), except that it has the location and properties of id-stx. When searching for a shadowing binding, bindings from unsealed internal-definition contexts are ignored.

Otherwise, the result is the same as id-stx with its module bindings (if any) removed from its lexical information, and the lexical information of the current module context (if any) added.

Thus, the result is an identifier corresponding to the innermost shadowing of id-stx in the current context if it is shadowed, and a module-contextless version of id-stx otherwise.

If id-stx is tainted or armed, then the resulting identifier is tainted.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

The syntax-local-armer function is needed by macro-generating macros, where a syntax object in the generated macro needs to be protected using the code inspector of the generating macro’s module.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

This procedure is potentially useful when m-id has a transformer binding that records some orig-id, and a use of m-id introduces a binding of orig-id. In that case, the syntax marks in the use of m-id since the binding of m-id should be transferred to the binding instance of orig-id, so that it captures uses with the same lexical context as the use of m-id.

More typically, however, syntax-local-make-delta-introducer should be used, since it cooperates with rename transformers.

If ext-stx is tainted or armed, then an identifier result from the created procedure is tainted.

The exn:fail:contract exception is raised if id or any identifier in its rename-transformer chain has no binding.

This procedure must be called during the dynamic extent of a syntax transformer application by the expander or while a module is visited, otherwise the exn:fail:contract exception is raised.

It returns two lists of identifiers corresponding to all definitions within the module being expanded. This information is used for implementing provide sub-forms like all-defined-out.

The first result list corresponds to phase 0 (i.e., normal) definitions, and the second corresponds to phase -1 (i.e., for-syntax) definitions.

It returns an association list mapping phase levels to lists of identifiers. Each list of identifiers includes all bindings imported (into the module being expanded) using the module path mod-path, or all modules if mod-path is #f. The association list includes all identifiers imported with a phase-level shift, of all shifts if phase-level is #t.

When an identifier is renamed on import, the result association list includes the identifier by its internal name. Use identifier-binding to obtain more information about the identifier.

11.4.1 require Transformers

A transformer binding whose value is a structure with the prop:require-transformer property implements a derived require-spec for require.

The transformer is called with the syntax object representing its use as a require-spec within a require form, and the result must be two lists: a list of imports and a list of import-sources.

If the derived form contains a sub-form that is a require-spec, then it can call expand-import to transform the sub-require-spec to lists of imports and import sources.

See also define-require-syntax, which supports macro-style require transformers.

• local-id — the identifier to be bound within the importing module.

• src-sym — the external name of the binding as exported from its source module.

• src-mod-path — a module path (relative to the importing module) for the source of the imported binding.

• orig-stx — a syntax object for the source of the import, used for error reporting.

• mode — the phase level of the binding in the importing module.

• req-mode — the phase level shift of the import relative to the exporting module.

• orig-mode — the phase level of the binding as exported by the exporting module.

• mod-path-stx — a module path (relative to the importing module) for the source of the imported binding.

• mode — the phase level shift of the import.

11.4.2 provide Transformers

A transformer binding whose value is a structure with the prop:provide-transformer property implements a derived provide-spec for provide.

The transformer is called with the syntax object representing its use as a provide-spec within a provide form and a list of symbols representing the export modes specified by enclosing provide-specs. The result must be a list of exports.

If the derived form contains a sub-form that is a provide-spec, then it can call expand-export to transform the sub-provide-spec to a list of exports.

See also define-provide-syntax, which supports macro-style provide transformers.

• local-id — the identifier that is bound within the exporting module.

• out-sym — the external name of the binding.

• orig-stx — a syntax object for the source of the export, used for error reporting.

• protect? — indicates whether the identifier should be protected (see Code Inspectors).

• mode — the phase level of the binding in the exporting module.