5 Macro Transformer Helpers

5.1 Extracting Inferred Names

To support the propagation and merging of consistent properties during expansions, the value of the 'inferred-name property can be a tree formed with cons where all of the leaves are the same. For example, (cons 'name 'name) is equivalent to 'name, and (cons (void) (void)) is equivalent to #<void>.

If use-local? is #f, then syntax-local-name is not used. Provide use-local? as #f to construct a name for a syntax object that is not an expression currently being expanded.

5.2 Support for local-expand

5.3 Parsing define-like Forms

To generate the right-hand side, this function may need to insert uses of lambda. The lambda-id-stx argument provides a suitable lambda identifier.

If the definition is ill-formed, a syntax error is raised. If check-context? is true, then a syntax error is raised if (syntax-local-context) indicates that the current context is an expression context. The default value of check-context? is #t.

If opt+kws? is #t, then arguments of the form [id expr], keyword id, and keyword [id expr] are allowed, and they are preserved in the expansion.

If err-no-body? is true, then there must be a right-hand side expression or else it is a syntax error. The err-no-body? argument is true for uses of normalize-definition.

Added in version 6.1.1.8 of package base.

5.4 Flattening begin Forms

Added in version 6.1.0.3 of package base.

5.5 Expanding define-struct-like Forms

• struct:name-id

• ctr-name, or make-name-id if ctr-name is #f

• name-id?

• name-id-field, for each field in field-ids.

• set-name-id-field! (getter and setter names alternate).

• ....

If omit-sel? is true, then the selector names are omitted from the result list. If omit-set? is true, then the setter names are omitted from the result list.

The default src-stx is #f; it is used to provide a source location to the generated identifiers.

If no-ctr? is true, then the constructor name is omitted from the expansion-time information. Similarly, if no-type? is true, then the structure-type name is omitted.

A #t for the base-name means no super-type, #f means that the super-type (if any) is unknown, and an identifier indicates the super-type identifier.

The generate-struct-declaration procedure is called by a macro expander to generate the expansion, where the name-id, super-id-or-false, and field-id-list arguments provide the main parameters. The current-context argument is normally the result of syntax-local-context. The orig-stx argument is used for syntax errors. The optional omit-sel? and omit-set? arguments default to #f; a #t value suppresses definitions of field selectors or mutators, respectively.

The make-struct-type procedure is called to generate the expression to actually create the struct type. Its arguments are orig-stx, name-id-stx, defined-name-stxes, and super-info. The first two are as provided originally to generate-struct-declaration, the third is the set of names generated by build-struct-names, and the last is super-struct info obtained by resolving super-id-or-false when it is not #f, #f otherwise.

The result should be an expression whose values are the same as the result of make-struct-type. Thus, the following is a basic make-make-struct-type:

(lambda (orig-stx name-stx defined-name-stxes super-info)

#`(make-struct-type '#,name-stx

#,(and super-info (list-ref super-info 0))

#,(/ (- (length defined-name-stxes) 3) 2)

0 #f))

but an actual make-make-struct-type will likely do more.

5.6 Resolving include-like Paths

The source-stx specifies a syntax object whose source-location information determines relative-path resolution. The expr-stx is used for reporting syntax errors. The build-path-stx is usually #'build-path; it provides an identifier to compare to parts of path-spec-stx to recognize the build-path keyword.

5.7 Controlling Syntax Templates

The save-proc is applied to each syntax object in the representation of the original template (i.e., in template-stx). If constant-as-leaf? is #t, then save-proc is applied only to syntax objects that contain at least one pattern variable in a sub-form. The result of save-proc is provided back as the first argument to restore-proc-stx, which indicates a function with a contract (-> any/c syntax any/c any/c); the second argument to restore-proc-stx is the syntax object that syntax generates, and the last argument is a datum that have been processed recursively (by functions such as restore-proc-stx) and that normally would be converted back to a syntax object using the second argument’s context, source, and properties. Note that save-proc works at expansion time (with respect to the template form), while restore-proc-stx indicates a function that is called at run time (for the template form), and the data that flows from save-proc to restore-proc-stx crosses phases via quote.

The leaf-save-proc and leaf-restore-proc-stx procedures are analogous to save-proc and restore-proc-stx, but they are applied to leaves, so there is no third argument for recursively processed sub-forms. The function indicated by leaf-restore-proc-stx should have the contract (-> any/c syntax? any/c).

The leaf-datum-proc-stx procedure is applied to leaves that are not syntax objects, which can happen because pairs and the empty list are not always individually wrapped as syntax objects. The function should have the contract (-> any/c any/c). When constant-as-leaf? is #f, the only possible argument to the procedure is null.

The pvar-save and pvar-restore-stx procedures are analogous to save-proc and restore-proc-stx, but they are applied to pattern variables. The pvar-restore-stx procedure should have the contract (-> any/c syntax? any/c), where the second argument corresponds to the substitution of the pattern variable.

The cons-proc-stx procedure is used to build intermediate pairs, including pairs passed to restore-proc-stx and pairs that do not correspond to syntax objects.

The ellipses-end-stx procedure is an extra filter on the syntax object that follows a sequence of ... ellipses in the template. The procedure should have the contract (-> any/c any/c).

The following example illustrates a use of transform-template to implement a syntax/shape form that preserves the 'paren-shape property from the original template, even if the template code is marshaled within bytecode.

(define-for-syntax (get-shape-prop stx)

(syntax-property stx 'paren-shape))

(define (add-shape-prop v stx datum)

(syntax-property (datum->syntax stx datum stx stx stx)

'paren-shape

v))

(define-syntax (syntax/shape stx)

(syntax-case stx ()

[(_ tmpl)

(transform-template #'tmpl

#:save get-shape-prop

#:restore-stx #'add-shape-prop)]))

5.8 Creating Macro Transformers

If the macro identifier is used as the target of a set! form, then the set! form expands into the application of setter-stx to the set! expression’s right-hand side, if setter-stx is syntax; otherwise, the identifier is considered immutable and a syntax error is raised. If setter-stx is a procedure, it is applied to the entire set! expression.

Added in version 6.3 of package base.

5.9 Applying Macro Transformers

Unlike simply applying transformer to stx directly, using local-apply-transformer introduces the appropriate use-site scope and macro-introduction scope that would be added by the expander.

The context and intdef-ctxs arguments are treated the same way as the corresponding arguments to local-expand.

Added in version 6.90.0.29 of package base.