▼phc-toolkit
►22 Syntax object manipulation utilities
On this page:
stx-car
stx-cdr
stx-e
stx-pair?
stx-car/  c
stx-cdr/  c
stx-e/  c
Stx-List?
stx-list?
stx->list
stx-list/  c
stx-null?
stx-assoc
identifier->string
identifier→string
22.1 Transformers utilities
make-rest-transformer
make-id+  call-transformer
make-id+  call-transformer-delayed
22.2 Patching source locations
quasisyntax/  top-loc
syntax/  top-loc
quasisyntax/  whole-loc
syntax/  whole-loc
22.3 Untyped versions of syntax object manipulation utilities
stx-assoc
identifier->string
identifier→string
make-rest-transformer
make-id+  call-transformer
quasisyntax/  top-loc
syntax/  top-loc
quasisyntax/  whole-loc
syntax/  whole-loc
7.7
  top  ← prev  up  next → 

22 Syntax object manipulation utilities

Georges Dupéron <georges.duperon@gmail.com>

 (require phc-toolkit/stx) package: phc-toolkit

procedure

(stx-car v) → any/c

  v : (or/c (syntax/c pair?) pair?)
Typed version of stx-car from syntax/stx.

procedure

(stx-cdr v) → any/c

  v : (or/c (syntax/c pair?) pair?)
Typed version of stx-cdr from syntax/stx.

procedure

(stx-e v) → any/c

  v : (or/c (syntax/c any/c) any/c)
Typed version of syntax-e which also accepts objects which are not syntax (in which case the original object is returned).

procedure

(stx-pair? v) → Boolean

  v : Any
A predicate which returns true for pairs and for syntax pairs alike.

procedure

(stx-car/c car-c) → (→ Any (U #f Result))

  car-c : (→ Any Result)
Returns a contract similar to the one returned by (cons/c car-c any/c), but which accepts both syntax pairs (stx-pair?) and pairs (pair?), as long as their stx-car (car respectively) is accepted by car-c.

procedure

(stx-cdr/c cdr-c) → (→ Any (U #f Result))

  cdr-c : (→ Any Result)
Returns a contract similar to the one returned by (cons/c any/c cdr-c), but which accepts both syntax pairs (stx-pair?) and pairs (pair?), as long as their stx-cdr (cdr respectively) is accepted by cdr-c.

procedure

(stx-e/c e-c) → (→ Any (U #f Result))

  e-c : (→ Any Result)
Equivalent to (or/c e-c (syntax/c e-c)).

Also equivalent to (λ (v) (e-c (stx-e v))).

Returns a contract which accepts any value accepted by e-c. The contract also accepts any value v for which syntax? returns true and (syntax-e v) is accepted by e-c.

type

(Stx-List? A)

A polymorphic type which is defined as:
(U Null
   (Pairof A (Stx-List? A))
   (Syntaxof Null)
   (Syntaxof (Pairof A (Stx-List? A))))

procedure

(stx-list? v) → Boolean

  v : Any
A predicate for Stx-List?.

procedure

(stx->list l) → (Listof A)

  l : (Stx-List? A)
Turns into a list any syntax list, which can be any proper sequence of syntax pairs terminated by a syntax list or by #'(). If the value l is already a regular non-syntax list, a copy of the list is returned (note that this means that the returned list will most likely not be eq? to the original).

procedure

(stx-list/c l-c) → (→ Any (U #f Result))

  l-c : (→ Any Result)
Equivalent to:

(λ (v)
  (and (stx-list? v)
       (l-c (stx->list v))))

Returns a contract which accepts any list accepted by l-c. The contract also accepts any value v for which stx-list? returns true and (stx->list v) is accepted by e-c.

procedure

(stx-null? v) → Boolean

  v : Any
Returns #true for the empty list (null) and for any empty syntax list (#'()). Returns #false for any other value.

procedure

(stx-assoc id alist) → (U (Syntaxof (Pairof Identifier T)) #f)

  id : Identifier
  alist : (Syntaxof (Listof (Syntaxof (Pairof Identifier T))))
(stx-assoc id alist) → (U (Syntaxof (Pairof Identifier T)) #f)
  id : Identifier
  alist : (Listof (Syntaxof (Pairof Identifier T)))
(stx-assoc id alist) → (U (Pairof Identifier T) #f)
  id : Identifier
  alist : (Listof (Pairof Identifier T))
Like assoc, but operates on syntax association lists.

procedure

(identifier->string identifier) → String

  identifier : Identifier
(identifier→string identifier) → String
  identifier : Identifier
Equivalent to (symbol->string (syntax-e identifier)).

22.1 Transformers utilities

procedure

(make-rest-transformer tranformer-function)

 → (-> syntax? syntax?)
  tranformer-function : (-> syntax? syntax?)
Returns a transformer function which applies tranformer-function on the stx-cdr of its argument. It is a shorthand for:

(λ (stx)
  (syntax-case stx ()
    [(_ . rest) (f #'rest)]))

procedure

(make-id+call-transformer result) → (-> syntax? syntax?)

  result : syntax?
Returns a transformer function which returns:

  • the given result, when it is called as an identifier macro

  • (result arg ...) where the arg ... are the macro’s arguments (except the macro identifier itself), when it is called as a regular macro.

It is a shorthand for:

(λ (stx)
  (syntax-case stx ()
    [(_ . args) (quasisyntax/top-loc stx (#,result . args))]
    [id (identifier? #'id) result]))

procedure

(make-id+call-transformer-delayed result)

 → (-> syntax? syntax?)
  result : (-> syntax?)
Like make-id+call-transformer, but the result is wrapped in a function which is evaluated only when the returned transformer function is run. This is useful when the expression depends on some mutable context.

22.2 Patching source locations

syntax

(quasisyntax/top-loc stx-expr quasitemplate)

Like (quasisyntax/loc stx-expr quasitemplate), but the source location for all "top" parts of the resulting syntax object are updated, so long as their source location is the same as the source location for the topmost part of the quasitemplate.

In other words, this does a traversal of the syntax object and updates the source location of the traversed parts, but the traversal does not go within a part whose source file differs from that of the quasitemplate.

For example, in the following code, the source location of parts within user-code will not be updated (unless user-code originates from the same file as quasitemplate), but the source location of all other parts will be updated, including the begin identifier and its surrounding form (its surrounding "pair of parentheses"). In contrast, quasisyntax/loc would have updated only the topmost syntax object, i.e. the outermost "pair of parentheses" of the let form.

(λ (stx)
  (syntax-case stx ()
    [(_ . user-code)
     (with-syntax ([bg #'(begin . user-code)])
       (quasisyntax/top-loc stx (let () bg)))]))

syntax

(syntax/top-loc stx-expr quasitemplate)

Like (syntax/loc stx-expr quasitemplate), but the source location for all "top" parts of the resulting syntax object are updated, like is done by quasisyntax/top-loc.

syntax

(quasisyntax/whole-loc stx-expr quasitemplate)

Like (quasisyntax/top-loc stx-expr quasitemplate), but the source location for all parts of the resulting syntax object are updated if they belong to the same source file as the quasitemplate, not only the "top" ones.

In the following example, all parts of the syntax object which source file is the same as the macro will be updated, including those within user-code (e.g. if the user-code contains code generated by other macros from the same file.

(λ (stx)
  (syntax-case stx ()
    [(_ . user-code)
     (with-syntax ([bg #'(begin . user-code)])
       (quasisyntax/whole-loc stx (let () bg)))]))

This is usually not needed, as quasisyntax/top-loc would have updated the source location of 1, 2 and 3 and their surrounding syntax list (the "pair of parentheses" around them), since their surrounding syntax list comes from the same file as the macro:

(λ (stx)
  (syntax-case stx ()
    [(_ . user-function)
     (quasisyntax/top-loc stx
       (user-function 1 2 3))]))

syntax

(syntax/whole-loc stx-expr quasitemplate)

Like (syntax/top-loc stx-expr quasitemplate), but the source location for all parts of the resulting syntax object are updated if they belong to the same source file as the quasitemplate, not only the "top" ones, like is done by quasisyntax/whole-loc.

22.3 Untyped versions of syntax object manipulation utilities

 (require phc-toolkit/untyped/stx) package: phc-toolkit

syntax

stx-assoc

Untyped version of stx-assoc.

procedure

(identifier->string identifier) → String

  identifier : Identifier
(identifier→string identifier) → String
  identifier : Identifier
Untyped version of identifier->string and identifier→string.

syntax

make-rest-transformer

Untyped version of make-rest-transformer.

syntax

make-id+call-transformer

Untyped version of make-id+call-transformer.

syntax

quasisyntax/top-loc

Untyped version of quasisyntax/top-loc.

syntax

syntax/top-loc

Untyped version of syntax/top-loc.

syntax

quasisyntax/whole-loc

Untyped version of quasisyntax/whole-loc.

syntax

syntax/whole-loc

Untyped version of syntax/whole-loc.

  top  ← prev  up  next →