Version: 5.0.1
27 Syntax
| (require unstable/syntax) |
This library is unstable;
compatibility will not be maintained.
See Unstable for more information.
| (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.
| (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 DrRacket.) 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.
Examples: | ||
| > (wrong-syntax #'here "expected ~s" 'there) | ||
?: expected there | ||
| ||
eval:4:0: look: expected there at: here in: (look over here) |
A macro using wrong-syntax 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).
| (define/with-syntax pattern expr) |
Definition form of with-syntax. That is, it matches the
syntax object result of expr against pattern and
creates pattern variable definitions for the pattern variables of
pattern.
Examples: |
| > (define/with-syntax (px ...) #'(a b c)) |
| > (define/with-syntax (tmp ...) (generate-temporaries #'(px ...))) |
| > #'([tmp px] ...) |
#<syntax:7:0 ((a5 a) (b6 b) (c7 c))> |
| (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.
Examples: |
| > (define-pattern-variable name #'Alice) |
| > #'(hello name) |
#<syntax:9:0 (hello Alice)> |
| (with-temporaries (temp-id ...) . body) |
Evaluates body with each temp-id bound as a pattern
variable to a freshly generated identifier.
Example: |
| > (with-temporaries (x) #'(lambda (x) x)) |
#<syntax:10:0 (lambda (x8) x8)> |
| (generate-temporary [name-base]) → identifier? |
| name-base : any/c = 'g |
Generates one fresh identifier. Singular form of
generate-temporaries. If name-base is supplied, it
is used as the basis for the identifier’s name.
Generates a list of n fresh identifiers.
| (current-recorded-disappeared-uses) |
| → (or/c (listof identifier?) false/c) |
| (current-recorded-disappeared-uses ids) → void? |
| ids : (or/c (listof identifier?) false/c) |
Parameter for tracking disappeared uses. Tracking is “enabled” when
the parameter has a non-false value. This is done automatically by
forms like with-disappeared-uses.
| (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/record 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 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.
| (record-disappeared-uses ids) → void? |
| ids : (listof identifier?) |
If not used within the extent of a with-disappeared-uses form or similar, has no effect.
| (format-symbol fmt v ...) → symbol? |
| fmt : string? |
| v : (or/c string? symbol? identifier? keyword? char? number?) |
Like format, but produces a symbol. The format string must
use only ~a placeholders. Identifiers in the argument list
are automatically converted to symbols.
Example: |
| > (format-symbol "make-~a" 'triple) |
'make-triple |
| ||||||||||||||||||||||||||||||||||||||||||
| lctx : (or/c syntax? #f) | ||||||||||||||||||||||||||||||||||||||||||
| src : (or/c syntax? #f) = #f | ||||||||||||||||||||||||||||||||||||||||||
| props : (or/c syntax? #f) = #f | ||||||||||||||||||||||||||||||||||||||||||
| cert : (or/c syntax? #f) = #f | ||||||||||||||||||||||||||||||||||||||||||
| fmt : string? | ||||||||||||||||||||||||||||||||||||||||||
| v : (or/c string? symbol? identifier? keyword? char? number?) |
Like format-symbol, but converts the symbol into an
identifier using lctx for the lexical context, src
for the source location, props for the properties, and
cert for the inactive certificates. (See
datum->syntax.)
The format string must use only ~a placeholders. Identifiers in the argument list are automatically converted to symbols.
Examples: | |||||
| |||||
| > (make-pred pair) | |||||
#<procedure:pair?> | |||||
| > (make-pred none-such) | |||||
reference to undefined identifier: none-such? | |||||
| |||||
| > (better-make-pred none-such) | |||||
reference to undefined identifier: none-such? |
(Scribble doesn’t show it, but the DrRacket pinpoints the location of the second error but not of the first.)
This binding was added by Vincent St-Amour.
| ||||||||||||||||||||||||||||||||||||||||||
| lctx : (or/c syntax? #f) | ||||||||||||||||||||||||||||||||||||||||||
| src : (or/c syntax? #f) = #f | ||||||||||||||||||||||||||||||||||||||||||
| props : (or/c syntax? #f) = #f | ||||||||||||||||||||||||||||||||||||||||||
| cert : (or/c syntax? #f) = #f | ||||||||||||||||||||||||||||||||||||||||||
| fmt : string? | ||||||||||||||||||||||||||||||||||||||||||
| v : (or/c string? symbol? identifier? keyword? char? number?) |
Like format-id, but returned identifiers are guaranteed to be unique.
| ||||||||||||||
| intdef-ctx : internal-definition-context? | ||||||||||||||
| stx : syntax? |
Applies the renamings of intdef-ctx to stx.
| (syntax-local-eval stx [intdef-ctx]) → any |
| stx : syntax? |
| intdef-ctx : (or/c internal-definition-context? #f) = #f |
Evaluates stx as an expression in the current transformer
environment (that is, at phase level 1), optionally extended with
intdef-ctx.
Examples: | ||||||||
| ||||||||
| > (show-me (+ 2 5)) | ||||||||
| ||||||||
| > (define-for-syntax fruit 'apple) | ||||||||
| > (define fruit 'pear) | ||||||||
| > (show-me fruit) | ||||||||
|
The subsequent bindings were added by Sam Tobin-Hochstadt.
|
Similar to with-syntax, but the pattern variables are bound in the remaining
stx-exprs as well as the bodys, and the patterns need not
bind distinct pattern variables; later bindings shadow earlier bindings.
Example: | |||
| |||
#<syntax:22:0 ((val1) (val2))> |
| (syntax-map f stxl ...) → (listof A) |
| f : (-> syntax? A) |
| stxl : syntax? |
Example: |
| > (syntax-map syntax-e #'(a b c)) |
'(a b c) |
The subsequent bindings were added by Carl Eastlund <cce@racket-lang.org>.
| (syntax-list template ...) |
This form constructs a list of syntax objects based on the given templates. It
is equivalent to (syntax->list #'(template ...)).
Example: |
| > (with-syntax ([(x ...) #'(1 2 3)]) (syntax-list x ...)) |
'(#<syntax:3:0 1> #<syntax:3:0 2> #<syntax:3:0 3>) |
| ||||||||||||||||||||||||||||||||||||||||||
| datum : any/c | ||||||||||||||||||||||||||||||||||||||||||
| stx : (or/c false/c syntax?) = #f | ||||||||||||||||||||||||||||||||||||||||||
| src : src/c = stx | ||||||||||||||||||||||||||||||||||||||||||
| ctxt : (or/c false/c syntax?) = stx | ||||||||||||||||||||||||||||||||||||||||||
| prop : (or/c false/c syntax?) = stx | ||||||||||||||||||||||||||||||||||||||||||
| cert : (or/c false/c syntax?) = stx |
A wrapper for datum->syntax with keyword arguments.
The "master" keyword #:stx sets all attributes from a single syntax object, defaulting to #f for unadorned syntax objects.
The individual keywords #:src, #:ctxt, #:prop, and #:cert override #:stx for individual syntax object attributes. They control source src information, lexical context information, syntax object properties, and syntax certificates, respectively.
Examples: | ||
| ||
| > blank-stx | ||
#<syntax car> | ||
| > (syntax-e blank-stx) | ||
'car | ||
| > (free-identifier=? blank-stx #'car) | ||
#f | ||
| ||
| > full-stx | ||
#<syntax:7:0 car> | ||
| > (syntax-e full-stx) | ||
'car | ||
| > (free-identifier=? full-stx #'car) | ||
#t | ||
| ||
| > partial-stx | ||
#<syntax car> | ||
| > (syntax-e partial-stx) | ||
'car | ||
| > (free-identifier=? partial-stx #'car) | ||
#t |
27.1 Syntax Object Source Locations
| ||
|
These produce the directory and file name, respectively, of the path with which
stx is associated, or #f if stx is not associated
with a path.
Examples: | ||||
| ||||
| ||||
| > (syntax-source-directory stx1) | ||||
#<path:/tmp/dir/> | ||||
| > (syntax-source-file-name stx1) | ||||
#<path:somewhere.ss> | ||||
| ||||
| > (syntax-source-directory stx2) | ||||
#f | ||||
| > (syntax-source-directory stx2) | ||||
#f |
27.2 Macro Transformers
| (redirect-transformer id) → (-> syntax? syntax?) |
| id : identifier? |
Constructs a function that behaves like a rename transformer; it does not
cooperate with syntax-local-value like a rename transformer does, but
unlike a rename transformer it may be used as a function to transform a syntax
object referring to one identifier into a syntax object referring to another.
Examples: |
| > ((redirect-transformer #'x) #'a) |
#<syntax:3:0 x> |
| > ((redirect-transformer #'y) #'(a b c)) |
#<syntax:4:0 (y b c)> |
| (head-expand stx [stop-list] intdef-ctx) → syntax? | |||||||||
| stx : syntax? | |||||||||
| stop-list : (listof identifier?) = null | |||||||||
|
This function performs head expansion on stx. In other words, it uses
local-expand to expand stx until its head identifier is a core
form (a member of (kernel-form-identifier-list)) or a member of
stop-list, or until it can not be expanded further (e.g. due to error).
It is equivalent to (local-expand stx (syntax-local-context) (append stop-ids (kernel-form-identifier-list) intdef-ctx)).
| (trampoline-transformer f) → (-> syntax? syntax?) |
| f : (-> (-> syntax? void?) (-> syntax? syntax?) syntax? syntax?) |
Produces a transformer that can emit multiple results during macro expansion, to
be spliced together via begin. This can be useful for compound
expansion that relies on transformer definitions, as well as on expansion state
that is difficult to marshall.
Specifically, f is invoked with three arguments. The first is the function used to emit intermediate results (other than the last one). The second applies the syntax mark used for the entire expansion; syntax-local-introduce will not be reliable during this process. The third is the syntax object to expand.
Examples: | ||||||||||||||
| ||||||||||||||
| ||||||||||||||
| ||||||||||||||
3 |
| (quote-transformer x) → syntax? |
| x : any/c |
Produces a syntax object representing an expression that reconstructs x
when executed, including faithfully reconstructing any syntax objects contained
in x. Note that quote normally converts syntax objects to
non-syntax data, and quote-syntax does the opposite.
Examples: | |||||
| > (define-for-syntax x (list 1 #'(2 3) 4)) | |||||
| |||||
| > (the-many-faces-of-x) | |||||
'((1 (2 3) 4) #<syntax (1 (2 3) 4)> (1 #<syntax:3:0 (2 3)> 4)) |