1 Syntax Object Helpers

1.1 Deconstructing Syntax Objects

(require syntax/stx)

(stx-null? v) → boolean?

v : any/c

Returns #t if v is either the empty list or a syntax object representing the empty list (i.e., syntax-e on the syntax object returns the empty list).

(stx-pair? v) → boolean?

v : any/c

Returns #t if v is either a pair or a syntax object representing a pair (see syntax pair).

(stx-list? v) → boolean?

v : any/c

Returns #t if v is a list, or if it is a sequence of pairs leading to a syntax object such that syntax->list would produce a list.

(stx->list stx-list) → list?

stx-list : stx-list?

Produces a list by flatting out a trailing syntax object using syntax->list.

(stx-car v) → any

v : stx-pair?

Takes the car of a syntax pair.

(stx-cdr v) → any

v : stx-pair?

Takes the cdr of a syntax pair.

(module-or-top-identifier=? a-id b-id) → boolean?

a-id : identifier?

b-id : identifier?

Returns #t if a-id and b-id are free-identifier=?, or if a-id and b-id have the same name (as extracted by syntax-e) and a-id has no binding other than at the top level.

This procedure is useful in conjunction with syntax-case* to match procedure names that are normally bound by MzScheme. For example, the include macro uses this procedure to recognize build-path; using free-identifier=? would not work well outside of module, since the top-level build-path is a distinct variable from the MzScheme export (though it’s bound to the same procedure, initially).

1.2 Matching Fully-Expanded Expressions

(require syntax/kerncase)

(kernel-syntax-case stx-expr trans?-expr clause ...)

A syntactic form like syntax-case*, except that the literals are built-in as the names of the primitive PLT Scheme forms as exported by scheme/base; see Fully Expanded Programs.

The trans?-expr boolean expression replaces the comparison procedure, and instead selects simply between normal-phase comparisons or transformer-phase comparisons. The clauses are the same as in syntax-case*.

The primitive syntactic forms must have their normal bindings in the context of the kernel-syntax-case expression. Beware that kernel-syntax-case does not work in a module whose language is mzscheme, since the binding of if from mzscheme is different than the primitive if.

(kernel-syntax-case* stx-expr trans?-expr (extras ...) clause ...)

A syntactic form like kernel-syntax-case, except that it takes an additional list of extra literals that are in addition to the primitive PLT Scheme forms.

(kernel-form-identifier-list) → (listof indentifier?)

Returns a list of identifiers that are bound normally, for-syntax, and for-template to the primitive PLT Scheme forms for expressions. This function is useful for generating a list of stopping points to provide to local-expand.

1.3 Hashing on bound-identifier=? and free-identifier=?

(require syntax/boundmap)

(make-bound-identifier-mapping) → bound-identifier-mapping?

Produces a hash-table-like value for storing a mapping from syntax identifiers to arbitrary values.

The mapping uses bound-identifier=? to compare mapping keys, but also uses a hash table based on symbol equality to make the mapping efficient in the common case (i.e., where non-equivalent identifiers are derived from different symbolic names).

(bound-identifier-mapping? v) → boolean?

v : any/c

Returns #t if v was produced by make-bound-identifier-mapping, #f otherwise.

(bound-identifier-mapping-get   bound-map             id            [ failure-thunk])   →   any

bound-map : bound-identifier-mapping?

id : identifier?

failure-thunk   :   any/c       =   (lambda () (raise (make-exn:fail ....)))

Like hash-table-get for bound-identifier mappings.

(bound-identifier-mapping-put!   bound-map             id             v)   →   void?

bound-map : bound-identifier-mapping?

id : identifier?

v : any/c

Like hash-table-put! for bound-identifier mappings.

(bound-identifier-mapping-for-each   bound-map             proc)   →   void?

bound-map : boud-identifier-mapping?

proc : (identifier? any/c . -> . any)

Like hash-table-for-each.

(bound-identifier-mapping-map   bound-map             proc)   →   (listof any?)

bound-map : bound-identifier-mapping?

proc : (identifier? any/c . -> . any)

Like hash-table-map.

(make-free-identifier-mapping) → free-identifier-mapping?

Produces a hash-table-like value for storing a mapping from syntax identifiers to arbitrary values.

The mapping uses free-identifier=? to compare mapping keys, but also uses a hash table based on symbol equality to make the mapping efficient in the common case (i.e., where non-equivalent identifiers are derived from different symbolic names at their definition sites).

(free-identifier-mapping? v) → boolean?

v : any/c

Returns #t if v was produced by make-free-identifier-mapping, #f otherwise.

(free-identifier-mapping-get   free-map             id            [ failure-thunk])   →   any

free-map : free-identifier-mapping?

id : identifier?

failure-thunk   :   any/c       =   (lambda () (raise (make-exn:fail ....)))

Like hash-table-get for free-identifier mappings.

(free-identifier-mapping-put! free-map id v) → void?

free-map : free-identifier-mapping?

id : identifier?

v : any/c

Like hash-table-put! for free-identifier mappings.

(free-identifier-mapping-for-each   free-map             proc)   →   void?

free-map : free-identifier-mapping?

proc : (identifier? any/c . -> . any)

Like hash-table-for-each.

(free-identifier-mapping-map free-map proc) → (listof any?)

free-map : free-identifier-mapping?

proc : (identifier? any/c . -> . any)

Like hash-table-map.

(make-module-identifier-mapping) → module-identifier-mapping?

(module-identifier-mapping? v) → boolean?   v : any/c

(module-identifier-mapping-get   module-map             id            [ failure-thunk])   →   any   module-map : module-identifier-mapping?   id : identifier?    failure-thunk   :   any/c       =   (lambda () (raise (make-exn:fail ....)))

(module-identifier-mapping-put!   module-map             id             v)   →   void?   module-map : module-identifier-mapping?   id : identifier?   v : any/c

(module-identifier-mapping-for-each   module-map             proc)   →   void?   module-map : module-identifier-mapping?   proc : (identifier? any/c . -> . any)

(module-identifier-mapping-map   module-map             proc)   →   (listof any?)   module-map : module-identifier-mapping?   proc : (identifier? any/c . -> . any)

The same as make-module-identifier-mapping, etc.

1.4 Rendering Syntax Objects with Formatting

(require syntax/to-string)

(syntax->string stx-list) → string?

stx-list : stx-list?

Builds a string with newlines and indenting according to the source locations in stx-list; the outer pair of parens are not rendered from stx-list.

1.5 Computing the Free Variables of an Expression

(require syntax/free-vars)

(free-vars expr-stx) → (listof identifier?)

expr-stx : syntax?

Returns a list of free lambda- and let-bound identifiers in expr-stx. The expression must be fully expanded (Fully Expanded Programs).

1.6 Legacy Zodiac Interface

(require syntax/zodiac)

(require syntax/zodiac-unit)

(require syntax/zodiac-sig)

The interface is similar to Zodiac – enough to be useful for porting – but different in many ways. See the source "zodiac-sig.ss" for details. New software should not use this compatibility layer.