7 Syntax Objects

(require (planet cce/scheme:4:1/syntax))

This module provides tools for macro transformers.

7.1 Contracts

(syntax-datum/c datum/c) → flat-contract?

datum/c : any/c

Recognizes syntax objects stx such that (syntax->datum stx) satisfies datum/c.

(syntax-listof/c elem/c) → flat-contract?

elem/c : any/c

Recognizes syntax objects stx such that (syntax->list stx) satisfies (listof elem/c).

(syntax-list/c elem/c ...) → flat-contract?

elem/c : any/c

Recognizes syntax objects stx such that (syntax->list stx) satisfies (list/c elem/c ...).

7.2 Syntax Lists

(syntax-map f stx) → (listof A)

f : (-> syntax? A)

stx : syntax?

Performs (map f (syntax->list stx)).

Examples:

> (syntax-map syntax-e #'(a (b c) d))

(a (#<syntax:1:0> #<syntax:1:0>) d)

7.3 Syntax Conversions

(to-syntax   datum            [ #:stx stx             #:src src             #:ctxt ctxt             #:prop prop             #:cert cert])   →   syntax?

datum : any/c

stx : (or/c false/c syntax?) = #f

src : (or/c false/c syntax?) = 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 location information, lexical context information, syntax object properties, and syntax certificates, respectively.

Examples:

(define blank-stx (to-syntax 'car))

> blank-stx

#<syntax>

> (syntax-e blank-stx)

car

> (free-identifier=? blank-stx #'car)

#f

(define full-stx (to-syntax 'car #:stx #'here))

> full-stx

#<syntax:5:0>

> (syntax-e full-stx)

car

> (free-identifier=? full-stx #'car)

#t

(define partial-stx (to-syntax 'car #:ctxt #'here))

> partial-stx

#<syntax>

> (syntax-e partial-stx)

car

> (free-identifier=? partial-stx #'car)

#t

(to-datum x) → (not/c syntax?)

x : any/c

A wrapper for syntax->datum. Produces (syntax->datum x) if x is a syntax object and x otherwise.

Examples:

> (to-datum #'(a b c))

(a b c)

> (to-datum (list #'a #'b #'c))

(#<syntax:2:0> #<syntax:2:0> #<syntax:2:0>)

7.4 Source Locations

(syntax-source-directory stx) → (or/c path? #f)   stx : syntax?

(syntax-source-file-name stx) → (or/c path? #f)   stx : syntax?

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:

(define loc     (list (build-path "/tmp" "dir" "somewhere.ss")           #f #f #f #f))

(define stx1 (datum->syntax #f 'somewhere loc))

> (syntax-source-directory stx1)

#<path:/tmp/dir/>

> (syntax-source-file-name stx1)

#<path:somewhere.ss>

(define stx2 (datum->syntax #f 'nowhere #f))

> (syntax-source-directory stx2)

#f

> (syntax-source-directory stx2)

#f

(syntax-source-planet-package stx)   →   (or/c (list/c string?               string?               exact-nonnegative-integer?               exact-nonnegative-integer?)        #f)   stx : syntax?

(syntax-source-planet-package-owner stx) → (or/c string? #f)   stx : syntax?

(syntax-source-planet-package-name stx) → (or/c string? #f)   stx : syntax?

(syntax-source-planet-package-major stx)  → (or/c exact-nonnegative-integer? #f)   stx : syntax?

(syntax-source-planet-package-minor stx)  → (or/c exact-nonnegative-integer? #f)   stx : syntax?

(syntax-source-planet-package-symbol   stx            [ text])   →   (or/c symbol? #f)   stx : syntax?   text : (or/c text? #f) = #f

These functions extract the planet package with which stx is associated, if any, based on its source location information and the currently installed set of planet packages. They produce, respectively, the planet package s-expression, its owner, name, major version number, minor version number, or a symbol corresponding to a planet module path. They each produce #f if stx is not associated with a planet package.

Examples:

(define loc     (list (build-path (current-directory) "file.ss")           #f #f #f #f))

(define stx (datum->syntax #f 'stx loc))

> (syntax-source-planet-package stx)

("cce" "scheme.plt" 4 1)

> (syntax-source-planet-package-owner stx)

"cce"

> (syntax-source-planet-package-name stx)

"scheme.plt"

> (syntax-source-planet-package-major stx)

4

> (syntax-source-planet-package-minor stx)

1

> (syntax-source-planet-package-symbol stx)

cce/scheme:4:1

> (syntax-source-planet-package-symbol stx "there")

cce/scheme:4:1/there

7.5 Syntax Errors

current-syntax : (parameter/c (or/c syntax? false/c))

A parameter that may be used to store the current syntax object being transformed. It is not used by the expander; you have to assign to it yourself. This parameter is used by syntax-error, below. It defaults to #f.

(syntax-error stx fmt arg ...) → none/c

stx : syntax?

fmt : string?

arg : any/c

Raises a syntax error based on the locations of (current-syntax) and stx, with (format fmt arg ...) as its message.

Examples:

(define stx #'(a b c))

> (parameterize ([current-syntax #f])       (syntax-error stx "~s location" 'general))

eval:1:0: a: general location in: (a b c)

> (parameterize ([current-syntax stx])       (syntax-error (car (syntax-e stx)) "~s location" 'specific))

eval:1:0: a: specific location at: a in: (a b c)

7.6 Pattern Bindings

(with-syntax* ([pattern expr] ...) body ...+)

Like with-syntax, but with nested scope.

Examples:

> (with-syntax* ([a #'id] [b #'a]) (syntax-e #'b))

id