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 ...)
> (syntax-source-module-name stx) : Symbol
stx : Syntax
This function works like syntax-source-module to produce the name of the module
from which stx originated. Unlike syntax-source-module, this always produces a
symbol: if syntax-source-module would produce a module path index, this function
resolves the path to a symbol; if syntax-source-module would produce #f, this
function generates a fresh, uninterned, dummy symbol.
================================================================================
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.