4 Utilities
The stxclass collection includes several utility modules. They are documented individually below.
As a shortcut, the stxclass/util module provides all of the contents of the separate utility modules:
| (require stxclass/util) |
The contents of the utility modules are not provided by the main stxclass module.
4.1 Error reporting
| (require stxclass/util/error) |
The scheme/base and scheme languages provide the raise-syntax-error procedure for reporting syntax errors. Using raise-syntax-error effectively requires passing around either a symbol indicating the special form that signals the error or else a “contextual” syntax object from which the special form’s name can be extracted. This library helps manage the contextual syntax for reporting errors.
| (current-syntax-context) → (or/c syntax? false/c) |
| (current-syntax-context stx) → void? |
| stx : (or/c syntax? false/c) |
The current contextual syntax object, defaulting to #f. It determines the special form name that prefixes syntax errors created by wrong-syntax, as follows:
If it is a syntax object with a 'report-error-as syntax property whose value is a symbol, then that symbol is used as the special form name. Otherwise, the same rules apply as in raise-syntax-error.
| (wrong-syntax stx format-string v ) → any |
| stx : syntax? |
| format-string : string? |
| v : any/c |
Raises a syntax error using the result of (current-syntax-context) as the “major” syntax object and the provided stx as the specific syntax object. (The latter, stx, is usually the one highlighted by DrScheme.) The error message is constructed using the format string and arguments, and it is prefixed with the special form name as described under current-syntax-context.
A macro using this system might set the syntax context at the very beginning of its transformation as follows:
| (define-syntax (my-macro stx) |
| (parameterize ((current-syntax-context stx)) |
| (syntax-case stx () |
| __))) |
Then any calls to wrong-syntax during the macro’s transformation will refer to my-macro (more precisely, the name that referred to my-macro where the macro was used, which may be different due to renaming, prefixing, etc).
A macro that expands into a helper macro can insert its own name into syntax errors raised by the helper macro by installing a 'report-error-as syntax property on the helper macro expression. For example:
| (define-syntax (public-macro stx) |
| (syntax-case stx () |
| [(public-macro stuff) |
| (syntax-property |
| (syntax/loc stx (my-macro stuff other-internal-stuff)) |
| 'report-error-as |
| (syntax-e #'public-macro))])) |
4.2 Miscellaneous utilities
| (require stxclass/util/misc) |
| (define-pattern-variable id expr) |
Evaluates expr and binds it to id as a pattern variable, so id can be used in subsequent syntax patterns.
| (with-temporaries (temp-id ) . body) |
Evaluates body with each temp-id bound as a pattern variable to a freshly generated identifier.
For example, the following are equivalent:
| (with-temporaries (x) #'(lambda (x) x)) |
| (with-syntax ([(x) (generate-temporaries '(x))]) |
| #'(lambda (x) x)) |
| (generate-temporary) → identifier? |
Generates one fresh identifier. Singular form of generate-temporaries.
| (generate-n-temporaries n) → (listof identifier?) |
| n : exact-nonnegative-integer? |
Generates a list of n fresh identifiers.
| (with-catching-disappeared-uses body-expr) |
Evaluates the body-expr, catching identifiers looked up using syntax-local-value/catch. Returns two values: the result of body-expr and the list of caught identifiers.
| (with-disappeared-uses stx-expr) |
Evaluates the stx-expr, catching identifiers looked up using syntax-local-value/catch. Adds the caught identifiers to the 'disappeared-uses syntax property of the resulting syntax object.
| (syntax-local-value/catch id predicate) → any/c |
| id : identifier? |
| predicate : (-> any/c boolean?) |
Looks up id in the syntactic environment (as syntax-local-value). If the lookup succeeds and returns a value satisfying the predicate, the value is returned and id is recorded (“caught”) as a disappeared use. If the lookup fails or if the value does not satisfy the predicate, #f is returned and the identifier is not recorded as a disappeared use.
| (chunk-kw-seq stx table [context]) | ||||||||
| ||||||||
| stx : syntax? | ||||||||
| ||||||||
| context : (or/c syntax? false/c) = #f |
Parses a syntax list into keyword-argument “chunks” and a syntax list tail (the remainder of the syntax list). The syntax of the keyword arguments is specified by table, an association list mapping keywords to lists of checker procedures. The length of the checker list is the number of “arguments” expected to follow the keyword, and each checker procedure is applied to the corresponding argument. The result of the checker procedure is entered into the chunk for that keyword sequence. The same keyword can appear multiple times in the result list.
The context is used to report errors.
| (chunk-kw-seq/no-dups stx table [context]) | ||||||||
| ||||||||
| stx : syntax? | ||||||||
| ||||||||
| context : (or/c syntax? false/c) = #f |
Like chunk-kw-seq filtered by reject-duplicate-chunks.
The context is used to report errors.
| (reject-duplicate-chunks chunks) → void? |
| chunks : (listof (cons/c keyword? (cons/c (syntax/c keyword?) list?))) |
Raises a syntax error if it encounters the same keyword more than once in the chunks list.
The context is used to report errors.
4.3 Structs
| (require stxclass/util/struct) |
| (make struct-id v ) |
Constructs an instance of struct-id, which must be defined as a struct name. If struct-id has a different number of fields than the number of v values provided, make raises a compile-time error.