2.1Deconstructing Syntax Objects🔗 i

This procedure is useful in conjunction with syntax-case* to match procedure names that are normally bound by Racket. 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 racket/base export (though it’s bound to the same procedure, initially).

2.2Matching Fully-Expanded Expressions🔗 i

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 provides different bindings for these primitive syntactic forms, such as mzscheme which does not provide the primitive if and typed/racket which does not provide the primitive let-values among others.

In addition to the identifiers listed in Fully Expanded Programs, the list includes letrec-syntaxes+values , which is the core form for local expand-time binding and can appear in the result of local-expand .

Changed in version 6.90.0.27 of package base: Added quote-syntax and #%plain-module-begin to the list, which had previously been unintentionally missing.

2.3Dictionaries with Identifier Keys🔗 i

This module provides two implementations of identifier tables: dictionaries with identifier keys that use identifier-specific comparisons instead of eq? or equal? . Identifier tables implement the racket/dict interface, and they are available in both mutable and immutable variants.

2.4Sets with Identifier Keys🔗 i

This module provides identifier sets: sets with identifier keys that use identifier-specific comparisons instead of the usual equality operators such as eq? or equal? .

This module implements two kinds of identifier sets: one via free-identifier=? and one via bound-identifier=? . Each are available in both mutable and immutable variants and implement the gen:set , gen:stream , prop:sequence , and gen:equal+hash generic interfaces.

Identifier sets are implemented using identifier tables, in the same way that hash sets are implemented with hash tables.

2.5Hashing on bound-identifier=? and free-identifier=? 🔗 i

This library is for backwards-compatibility. Do not use it for new libraries; use syntax/id-table instead.

2.6Rendering Syntax Objects with Formatting🔗 i

2.7Computing the Free Variables of an Expression🔗 i

The inspector insp is used to disarm expr-stx and sub-expressions before extracting identifiers. The default insp is the declaration-time inspector of the syntax/free-vars module.

If module-bound? is non-false, the list of free variables also includes free module-bound identifiers.

2.8Replacing Lexical Context🔗 i

Typically, form is a syntax object, and then the result is also a syntax object. Otherwise, pairs, vectors, boxes, hash tables, and prefab structures are traversed (and copied for the result) to find syntax objects. Graph structure is not preserved in the result, and cyclic data structures will cause strip-context to never return.

Changed in version 7.7.0.10 of package base: Repaired to traverse hash tables in stx.

Syntax objects are found in form the same as in strip-context .

Changed in version 7.7.0.10 of package base: Repaired to traverse hash tables in stx.

2.9Helpers for Processing Keyword Syntax🔗 i

The syntax/keyword module contains procedures for parsing keyword options in macros.

A keyword-table is a dictionary (dict? ) mapping keywords to lists of check-procedures. (Note that an association list is a suitable dictionary.) The keyword’s arity is the length of the list of procedures.

A check procedure consumes the syntax to check and a context syntax object for error reporting and either raises an error to reject the syntax or returns a value as its parsed representation.

Parsed options are represented as an list of option entries. Each entry contains the keyword, the syntax of the keyword (for error reporting), and the list of parsed values returned by the keyword’s list of check procedures. The list contains the parsed options in the order they appeared in the input, and a keyword that occurs multiple times in the input occurs multiple times in the options list.

Parsing stops normally when the syntax list does not have a keyword at its head (it may be empty, start with a non-keyword term, or it may be a non-list syntax object). Two values are returned: the parsed options and the rest of the syntax (generally either a syntax object or a list of syntax objects).

A variety of errors and exceptional conditions can occur during the parsing process. The following keyword arguments determine the behavior in those situations.

The #:contextctx argument is used to report all errors in parsing syntax. In addition, ctx is passed as the final argument to all provided handler procedures. Macros using parse-keyword-options should generally pass the syntax object for the whole macro use as ctx.

If no-duplicates? is a non-false value, then duplicate keyword options are not allowed. If a duplicate is seen, the keyword’s associated check procedures are not called and an incompatibility is reported.

The incompatible argument is a list of incompatibility entries, where each entry is a list of at least two keywords. If any keyword in the entry occurs after any other keyword in the entry, an incompatibility is reported.

Note that including a keyword in an incompatibility entry does not prevent it from occurring multiple times. To disallow duplicates of some keywords (as opposed to all keywords), include those keywords in the incompatible list as being incompatible with themselves. That is, include them twice:

;Disallow duplicates of only the #:foo keyword

(parse-keyword-options ....#:incompatible'((#:foo#:foo)))

When an incompatibility occurs, the incompatible-handler is tail-called with the two keywords causing the incompatibility (in the order that they occurred in the syntax list, so the keyword triggering the incompatibility occurs second), the syntax list starting with the occurrence of the second keyword, and the context (ctx). If the incompatibility is due to a duplicate, the two keywords are the same.

When a keyword is not followed by enough arguments according to its arity in table, the too-short-handler is tail-called with the keyword, the options parsed thus far, the syntax list starting with the occurrence of the keyword, and ctx.

When a keyword occurs in the syntax list that is not in table, the not-in-table-handler is tail-called with the keyword, the options parsed thus far, the syntax list starting with the occurrence of the keyword, and ctx.

Handlers typically escape—all of the default handlers raise errors—but if they return, they should return two values: the parsed options and a syntax object; these are returned as the results of parse-keyword-options .