Syntax-Utils: Syntax and macro utilities

_Syntax-Utils: Syntax and macro utilities_

Written by: Carl Eastlund (cce at ccs dot neu dot edu)
Keywords: _syntax_, _macro_, _transformer_, _template_, _identifier_, _phase_

This software is distributed under a BSD-style license (see license.txt).

================================================================================

Functions and macros provided by _syntax-utils.ss_:

> (syntax-datum/c datum/c) : FlatContract
  datum/c : FlatContract or (Any -> Boolean)

Produces a flat contract which accepts stx if and only if datum/c accepts
(syntax-object->datum stx).
Example:
(define stx (datum->syntax-object (cons 'one 2)))
(provide/contract
 [stx (syntax-datum/c (cons/c symbol? number?))])

> (syntax-list/c stx/c) : FlatContract
  stx/c : FlatContract or (Syntax -> Boolean)

Produces a flat contract which accepts stx if and only if stx/c accepts each
element of (syntax->list stx).
Example:
(define stx (datum->syntax-object (list 'one 'two 'three)))
(provide/contract
 [stx (syntax-list/c identifier?)])

> (syntax-map f stx) : (Listof Result)
  f : Syntax -> Result
  stx : (Syntax List)

Maps a function over elements along the spine of a syntax object.
Example: (syntax-map syntax-e (syntax (a b c))) = '(a b c)

> (syntax-append prefix id suffix) : Identifier
  prefix : String
  id : Identifier
  suffix : String

Adds a prefix and suffix to an identifier's name, preserving other syntactic
properties.
Example: (syntax-append "exn:" (syntax fail) "?") = (syntax exn:fail?)

> (syntax-prefix prefix id) : Identifier
  prefix : String
  id : Identifier

Adds a prefix to an identifier's name, preserving other syntactic properties.
Equivalent to (syntax-append prefix id "").
Example: (syntax-prefix "list:" (syntax map)) = (syntax list:map)

> (syntax-suffix id suffix) : Identifier
  id : Identifier
  suffix : String

Adds a suffix to an identifier's name, preserving other syntactic properties.
Equivalent to (syntax-append "" id suffix).
Example: (syntax-suffix (syntax map) "-list") = (syntax map-list)

> (string->identifier name [stx]) : Identifier
  name : String
  stx : Syntax or #f

Constructs an identifier from a string.  The optional argument stx provides
location and context information (if provided and not #f).
Example: (string->identifier "it") = (syntax it)

> (identifier->string-literal id) : (Syntax String)
  id : Identifier

Constructs a string literal syntax object from an identifier.
Example: (identifier->string-literal (syntax it)) = (syntax "it")

> (identifier->string id) : String
  id : Identifier

Constructs a string from an identifier.
Example: (identifier->string (syntax it)) = "it"

> (identifier-name=? id1 id2) : Boolean
  id1 : Identifier
  id2 : Identifier

Reports whether id1 and id2 have the same name, regardless of context.
Example:
(identifier-name=? (syntax if) (datum->syntax-object #f (quote if) #f)) = #t

> (syntax-case-by-name stx (literal-id ...) clause ...)

This macro behaves as syntax-case, but uses identifier-name=? to compare each
literal-id to identifiers in stx.  It is equivalent to:
(syntax-case* stx (literal-id ...) identifier-name=? clause ...)

================================================================================

Functions and macros provided by _phase.ss_:

> (in-phase1 expr)

This macro evaluates expr as an expression in phase 1 (compile-time).  It does
not get re-evaluated if a containing module is later required (in contract to
begin-for-syntax).

> (in-phase1/pass2 expr)

As in-phase1 above, but evaluates expr during the second pass of phase1, after
all forms have been head-expanded.