Version: 4.2.1.8
5 Macros
5.1 Syntax Objects
| (require (planet cce/scheme:5:0/syntax)) |
This module provides tools for macro transformers.
5.1.1 Contracts
| (syntax-datum/c datum/c) → flat-contract? |
| datum/c : any/c |
| (syntax-listof/c elem/c) → flat-contract? |
| elem/c : any/c |
| (syntax-list/c elem/c ...) → flat-contract? |
| elem/c : any/c |
5.1.2 Syntax Lists
| (syntax-list template ...) |
This form constructs a list of syntax objects based on the given templates. It
is equivalent to (syntax->list #'(template ...)).
Example: |
| > (with-syntax ([(x ...) #'(1 2 3)]) (syntax-list x ...)) |
(#<syntax:1:0 1> #<syntax:1:0 2> #<syntax:1:0 3>) |
| (syntax-map f stx) → (listof A) |
| f : (-> syntax? A) |
| stx : syntax? |
Example: |
| > (syntax-map syntax-e #'(a (b c) d)) |
(a (#<syntax:1:0 b> #<syntax:1:0 c>) d) |
5.1.3 Syntax Conversions
| ||||||||||||||||||||||||||||||||||||||||||
| datum : any/c | ||||||||||||||||||||||||||||||||||||||||||
| stx : (or/c false/c syntax?) = #f | ||||||||||||||||||||||||||||||||||||||||||
| src : src/c = 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 src information, lexical context information, syntax object properties, and syntax certificates, respectively.
Examples: | ||
| ||
| > blank-stx | ||
#<syntax car> | ||
| > (syntax-e blank-stx) | ||
car | ||
| > (free-identifier=? blank-stx #'car) | ||
#f | ||
| ||
| > full-stx | ||
#<syntax:5:0 car> | ||
| > (syntax-e full-stx) | ||
car | ||
| > (free-identifier=? full-stx #'car) | ||
#t | ||
| ||
| > partial-stx | ||
#<syntax car> | ||
| > (syntax-e partial-stx) | ||
car | ||
| > (free-identifier=? partial-stx #'car) | ||
#t |
Examples: |
| > (to-datum #'(a b c)) |
(a b c) |
| > (to-datum (list #'a #'b #'c)) |
(#<syntax:2:0 a> #<syntax:2:0 b> #<syntax:2:0 c>) |
5.1.4 Source Locations
5.1.4.1 Source Location Representations
This contract recognizes various representations of source locations, including
srcloc structures and those accepted by datum->syntax: syntax
objects, source location lists, source location vectors, and #f.
| ||||||||||||
| ||||||||||||
| ||||||||||||
|
These functions combine multiple source locations and convert them to a specific
format. If all provided source locations come from the same source, the result
is a source location from the same source that spans all the lines, columns, and
positions included in the originals. If no source locations are provided, or
locations from different sources are provided, the result is a source location
with no information (#f for source, line, column, position, and span).
Examples: |
| > (src->srcloc (datum->syntax #f null (list 'source 2 3 4 5))) |
#(struct:srcloc source 2 3 4 5) |
| > (src->syntax (make-srcloc 'source 2 3 4 5)) |
#<syntax:2:3 ()> |
| > (src->list (list 'source 2 3 4 5) (vector 'source 6 7 8 9)) |
(source 2 3 4 13) |
| > (src->vector) |
#(#f #f #f #f #f) |
5.1.4.2 Syntax Object Source Locations
| ||
|
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: | ||||
| ||||
| ||||
| > (syntax-source-directory stx1) | ||||
#<path:/tmp/dir/> | ||||
| > (syntax-source-file-name stx1) | ||||
#<path:somewhere.ss> | ||||
| ||||
| > (syntax-source-directory stx2) | ||||
#f | ||||
| > (syntax-source-directory stx2) | ||||
#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: | ||||
| ||||
| ||||
| > (syntax-source-planet-package stx) | ||||
("cce" "scheme.plt" 5 0) | ||||
| > (syntax-source-planet-package-owner stx) | ||||
"cce" | ||||
| > (syntax-source-planet-package-name stx) | ||||
"scheme.plt" | ||||
| > (syntax-source-planet-package-major stx) | ||||
5 | ||||
| > (syntax-source-planet-package-minor stx) | ||||
0 | ||||
| > (syntax-source-planet-package-symbol stx) | ||||
cce/scheme:5:0 | ||||
| > (syntax-source-planet-package-symbol stx "there") | ||||
cce/scheme:5:0/there |
| (make-planet-path stx id) → syntax? |
| stx : syntax? |
| id : (or/c identifier? #f) |
Constructs a syntax object representing a require spec for the planet package
from which stx arises, with suffix id (if any).
Examples: | ||||
| ||||
| ||||
| > (make-planet-path stx #f) | ||||
#<syntax (planet cce/scheme:5:0)> | ||||
| > (make-planet-path stx #'there) | ||||
#<syntax:4:0 (planet cce/scheme:5:0/there)> |
5.1.5 Macro Transformers
| (redirect-transformer id) → (-> syntax? syntax?) |
| id : identifier? |
Constructs a function that behaves like a rename transformer; it does not
cooperate with syntax-local-value like a rename transformer does, but
unlike a rename transformer it may be used as a function to transform a syntax
object referring to one identifier into a syntax object referring to another.
Examples: |
| > ((redirect-transformer #'x) #'a) |
#<syntax:1:0 x> |
| > ((redirect-transformer #'y) #'(a b c)) |
#<syntax:2:0 (y b c)> |
| (head-expand stx stop-list) → syntax? |
| stx : syntax? |
| stop-list : (listof identifier?) |
This function performs head expansion on stx. In other words, it uses
local-expand to expand stx until its head identifier is a core
form (a member of (full-kernel-form-identifier-list)) or a member of
stop-list, or until it can not be expanded further (e.g. due to error).
It is equivalent to (local-expand stx (syntax-local-context) (append stop-ids (full-kernel-form-identifier-list) #f)).
This function produces the full list of identifiers that may be found in fully
expanded code produced by expand, local-expand, and related
functions. It is similar to kernel-form-identifier-list, except that
in prior versions of PLT Scheme that excluded module top-level forms from the
list, this function includes them.
Example: |
| > (full-kernel-form-identifier-list) |
(#<syntax #%require> #<syntax #%provide> #<syntax module> #<syntax #%plain-module-begin> #<syntax begin> #<syntax begin0> #<syntax define-values> #<syntax define-syntaxes> #<syntax define-values-for-syntax> #<syntax set!> #<syntax let-values> #<syntax letrec-values> #<syntax #%plain-lambda> #<syntax case-lambda> #<syntax if> #<syntax quote> #<syntax letrec-syntaxes+values> #<syntax with-continuation-mark> #<syntax #%expression> #<syntax #%plain-app> #<syntax #%top> #<syntax #%datum> #<syntax #%variable-reference>) |
5.1.6 Syntax Errors
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: | ||
| ||
| ||
eval:1:0: a: general location in: (a b c) | ||
| ||
eval:1:0: a: specific location at: a in: (a b c) |
5.1.7 Pattern Bindings
| (with-syntax* ([pattern expr] ...) body ...+) |
Like with-syntax, but with nested scope.
Example: |
| > (with-syntax* ([a #'id] [b #'a]) (syntax-e #'b)) |
id |
5.2 Definitions
| (require (planet cce/scheme:5:0/define)) |
This module provides macros for creating and manipulating definitions.
5.2.1 Interleaving Definitions and Expressions
| (block def-or-expr ...) |
This expression establishes a lexically scoped block (i.e. an internal
definition context) in which definitions and expressions may be interleaved.
Its result is that of the last term (after begin-splicing), executed in
tail position, if the term is an expression; if there are no terms, or the last
term is a definition, its result is (void).
This form is equivalent to (begin-with-definitions def-or-expr ...).
Examples: | |||||||||||||||
| |||||||||||||||
| > (intersection (list 1 2 3) (list 2 3 4)) | |||||||||||||||
(3 2) |
5.2.2 Conditional Binding
| ||
| ||
| ||
|
These forms define each x (or f) if no such binding exists, or
do nothing if the name(s) is(are) already bound. The
define-values-if-unbound and define-syntaxes-if-unbound forms
raise a syntax error if some of the given names are bound and some are not.
These are useful for writing programs that are portable across versions of PLT Scheme with different bindings, to provide an implementation of a binding for versions that do not have it but use the built-in one in versions that do.
Examples: | ||
| > (define-if-unbound x 1) | ||
| > x | ||
1 | ||
| ||
| > (define-if-unbound y 3) | ||
| > y | ||
2 |
5.2.3 Renaming Definitions
| (define-renamings [new old] ...) |
This form establishes a rename transformer for each new identifier,
redirecting it to the corresponding old identifier.
Examples: |
| > (define-renamings [def define] [lam lambda]) |
| > (def plus (lam (x y) (+ x y))) |
| > (plus 1 2) |
3 |
5.2.4 Forward Declarations
| (declare-names x ...) |
This form provides forward declarations of identifiers to be defined later. It
is useful for macros which expand to mutually recursive definitions, including
forward references, that may be used at the PLT Scheme top level.
5.2.5 Definition Shorthands
| (define-with-parameter name parameter) |
Defines the form name as a shorthand for setting the parameter
parameter. Specifically, (name value body ...) is equivalent
to (parameterize ([parameter value]) body ...).
Examples: |
| > (define-with-parameter with-input current-input-port) |
| > (with-input (open-input-string "Tom Dick Harry") (read)) |
Tom |
| (define-single-definition define-one-name define-many-name) |
This form defines a marco define-one-name as a single identifier
definition form with function shorthand like define and
define-syntax, based on an existing macro define-many-name
which works like define-values or define-syntaxes.
Examples: |
| > (define-single-definition define-like define-values) |
| > (define-like x 0) |
| > x |
0 |
| > (define-like (f a b c) (printf "~s, ~s\n" a b) c) |
| > (f 1 2 3) |
1, 2 |
3 |
5.2.6 Effectful Transformation
| (in-phase1 e) |
This form executes e during phase 1 (the syntax transformation phase)
relative to its context, during pass 1 if it occurs in a head expansion
position.
| (in-phase1/pass2 e) |
This form executes e during phase 1 (the syntax transformation phase)
relative to its context, during pass 2 (after head expansion).