3.2.1 mischief/transform: Syntax Transformers

8.12

3.2.1 mischief/transform: Syntax Transformers🔗ℹ

3.2.1.1 Converting Values to/from Syntax🔗ℹ

procedure
(to-syntax x
[ #:stx stx
#:context context
#:source source
#:prop prop]) → syntax?
  x : any/c
  stx : (or/c syntax? #false) = #false
  context : (or/c syntax? #false) = stx
  source : source-location? = stx
  prop : (or/c syntax? #false) = stx

Converts x to a syntax object using the lexical context of context, the source location of source, and the syntax properties of prop, using stx for any of the above that are not provided. Equivalent to (datum->syntax context x (build-source-location-list source) prop).

Examples:

> (define stx (to-syntax 'car #:stx #'here))
> stx
#<syntax:eval:1:0 car>
> (build-source-location stx)
(srcloc 'eval 1 0 1 1)
> (free-identifier=? stx #'car)
#t

procedure
(to-datum x) → any/c
x : any/c

Replaces any syntax objects contained in x with their content; equivalent to (syntax->datum (datum->syntax #false x)).

Example:

> (to-datum (list #''(1 2 3) #'(#%datum . "text")))
'('(1 2 3) (#%datum . "text"))

procedure
(quote-transformer x) → syntax?
x : any/c

Produces a expression that reconstructs x when evaluated. Useful when x may contain syntax objects, which are not preserved by simply wrapping x in quote.

Example:

> (to-datum (quote-transformer (list '(1 2) #'(3 4))))
'`((1 2) ,(quote-syntax (3 4)))

3.2.1.2 Constructing Identifiers🔗ℹ

procedure
(fresh [ x
#:source source
#:add-suffix? add-suffix?]) → identifier?
   x : (or/c symbol? string? identifier? keyword? char? number?)
= 'fresh
  source : source-location? = (if (identifier? x) x #false)
  add-suffix? : boolean? = #true

Constructs an identifier with a unique binding named x, with a unique suffix if add-suffix? is true, and using the source location of source.

Examples:

> (fresh)
sym: undefined;
cannot use before initialization
> (fresh)
sym: undefined;
cannot use before initialization
> (define x #'x)
> (define fresh-x (fresh x #:add-suffix? #false))
> x
#<syntax:eval:9:0 x>
> fresh-x
#<syntax:eval:9:0 x>
> (free-identifier=? x fresh-x)
#f

procedure
(format-fresh fmt
arg ...
[ #:source source
#:add-suffix? add-suffix?]) → identifier?
  fmt : string?
  arg : (or/c symbol? string? identifier? keyword? char? number?)
  source : source-location? = #false
  add-suffix? : boolean? = #true

Equivalent to:

(fresh (format-symbol fmt arg ...)
#:source source
#:add-suffix? add-suffix?)

Example:

> (format-fresh "~a-~a" #'string #'length)
sym: undefined;
cannot use before initialization

procedure
(fresh-mark) → (-> syntax? syntax?)

An alias for make-syntax-introducer.

Examples:

> (define id1 (fresh))
sym: undefined;
cannot use before initialization
> (define mark (fresh-mark))
> (define id2 (mark id1))
id1: undefined;
cannot reference an identifier before its definition
  in module: 'program
> (define id3 (mark id2))
id2: undefined;
cannot reference an identifier before its definition
  in module: 'program
> (bound-identifier=? id1 id2)
id1: undefined;
cannot reference an identifier before its definition
  in module: 'program
> (bound-identifier=? id2 id3)
id2: undefined;
cannot reference an identifier before its definition
  in module: 'program
> (bound-identifier=? id1 id3)
id1: undefined;
cannot reference an identifier before its definition
  in module: 'program

procedure
(identifier-upcase id) → identifier?
  id : identifier?
procedure
(identifier-downcase id) → identifier?
  id : identifier?
procedure
(identifier-titlecase id) → identifier?
  id : identifier?
procedure
(identifier-foldcase id) → identifier?
  id : identifier?

Change the letters in the name of an identifier by analogy to string-upcase, string-downcase, string-titlecase, and string-foldcase.

Examples:

> (identifier-upcase #'Two-words)
#<syntax:eval:22:0 TWO-WORDS>
> (identifier-downcase #'Two-words)
#<syntax:eval:23:0 two-words>
> (identifier-titlecase #'Two-words)
#<syntax:eval:24:0 Two-Words>
> (identifier-foldcase #'Two-words)
#<syntax:eval:25:0 two-words>

3.2.1.3 Common Syntax Transformer Patterns🔗ℹ

procedure
(id-transform original replace) → syntax?
original : syntax?
replace : (or/c syntax? (-> identifier? syntax?))

Transforms the identifier that controls the expansion of original as a macro application, set! transformer application, or identifier macro reference. Replaces that identifier with replace if replace is a syntax object, or with the result of applying replace to the identifier if replace is a procedure.

Examples:

> (id-transform #'simple-identifier #'replacement)
#<syntax:eval:26:0 replacement>
> (id-transform #'(simple macro application) #'replacement)
#<syntax:eval:27:0 (#%app replacement macro application)>
> (id-transform #'(set! macro application) #'replacement)
#<syntax:eval:28:0 (set! replacement application)>

procedure
(id-transformer proc)
→ (and/c set!-transformer? (-> syntax? syntax?))
proc : (-> identifier? syntax?)

Produces a set! transformer that, when defined as a macro, applies proc to the name of the macro in any application.

Examples:

> (define x 1)
> (define-syntax X (id-transformer identifier-downcase))
> (set! X (add1 X))
> X
2

procedure
(set!-transformer proc)
→ (and/c set!-transformer? (-> syntax? syntax?))
proc : (-> syntax? syntax?)

Produces a set! transformer that can also be used as a procedure.

Examples:

> (define-for-syntax f
    (set!-transformer
      (lambda {x}
        #'(error 'undefined "Oh, no!"))))
> (define-syntax (x stx) (f stx))
> x
undefined: Oh, no!
> (x 1)
undefined: Oh, no!
> (set! x 1)
eval:37:0: set!: cannot mutate syntax identifier
  at: x
  in: (set! x 1)
> (define-syntax y f)
> y
undefined: Oh, no!
> (y 1)
undefined: Oh, no!
> (set! y 1)
undefined: Oh, no!

procedure
(rename-transformer id)
→ (and/c (-> syntax? syntax?) rename-transformer?)
id : identifier?
procedure
(rename-transformers id ...)
→
(and/c (-> syntax? syntax?) rename-transformer?)
...
id : identifier?

Produces one or many rename transformers that can also be used as procedures.

Examples:

> (define-syntaxes {pair left right}
(rename-transformers #'cons #'car #'cdr))
> (pair (left '(1 2)) (right '(3 4)))
'(1 4)
> (define-syntax (tuple stx)
((rename-transformer #'list) stx))
> tuple
#<procedure:list>
> (tuple 1 2 3)
'(1 2 3)

3.2.1.4 Phase 1 Helpers🔗ℹ

procedure
(syntax-error stx fmt x ...) → none/c
  stx : syntax?
  fmt : string?
  x : any/c

An alias for wrong-syntax.

procedure
(syntax-local-variable-reference) → variable-reference?

Produces an anonymous variable reference representing the context currently being expanded.

Examples:

> (module var-ref-example racket
    (require (for-syntax mischief/transform))
    (define-syntax (macro stx)
      (printf "Transforming: ~s\n"
        (resolved-module-path-name
          (variable-reference->resolved-module-path
            (syntax-local-variable-reference))))
      #'(begin))
    (macro))
Transforming: var-ref-example
> (require 'var-ref-example)

procedure
(check-missing-identifier actual expected)
→ (or/c identifier? #false)
actual : (listof identifier?)
expected : (listof identifier?)

If actual is missing a free-identifier=? counterpart for any identifier in expected, produces the first such identifier found. Otherwise, produces #false

Example:

> (check-missing-identifier
(list #'cons #'car #'cdr)
(list #'cons #'first #'rest))
#<syntax:eval:49:0 car>

1	Structured Debugging
2	Printing and Error Messages
3	Macros and Syntax Transformers
4	Modules
5	Definitions and Binding Forms
6	First-Order Datatypes
7	Functions and Flow Control
8	Typesetting Formats

3.1	Writing Simple Macros with mischief/ shorthand
3.2	General-Purpose Tools for Writing Macros
3.3	Advanced Tools for Writing Macros
3.4	Debugging Macros with mischief/ stepper

3.2.1	mischief/ transform: Syntax Transformers
3.2.2	mischief/ parse: Tools for syntax-parse

3.2.1.1	Converting Values to/ from Syntax
3.2.1.2	Constructing Identifiers
3.2.1.3	Common Syntax Transformer Patterns
3.2.1.4	Phase 1 Helpers