12.5 Syntax Parameters

► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

▼ | 12 | Macros

12.1 | Pattern-Based Syntax Matching
12.2 | Syntax Object Content
12.3 | Syntax Object Bindings
12.4 | Syntax Transformers
12.5 | Syntax Parameters
12.6 | Local Binding with Splicing Body
12.7 | Syntax Object Properties
12.8 | Syntax Taints
12.9 | Expanding Top-Level Forms
12.10 | File Inclusion
12.11 | Syntax Utilities

► | 12.5 | Syntax Parameters

12.5.1 | Syntax Parameter Inspection

On this page:

define-syntax-parameter
syntax-parameterize
define-rename-transformer-parameter
12.5.1`` Syntax Parameter Inspection
syntax-parameter-value
make-parameter-rename-transformer

top ← prev up next →

#### 12.5`` Syntax Parameters

(require racket/stxparam) | package: base

The bindings documented in this section are provided by the racket/stxparam library, not racket/base or racket.

> syntax (define-syntax-parameter id expr)

Binds id as syntax to a syntax parameter. The expr is an expression in the transformer environment that serves as the default value for the syntax parameter. The value is typically obtained by a transformer using syntax-parameter-value.

The id can be used with syntax-parameterize or syntax-parameter-value (in a transformer). If expr produces a procedure of one argument or a make-set!-transformer result, then id can be used as a macro. If expr produces a make-rename-transformer result, then id can be used as a macro that expands to a use of the target identifier, but syntax-local-value of id does not produce the target’s value.

Examples:

> > (define-syntax-parameter current-class #f)
> > (define-syntax-parameter yield (make-rename-transformer #'abort))
> > (define-syntax-parameter define/public
> (λ (stx)
> (raise-syntax-error #f "use of a class keyword not in a class" stx)))
> > (begin-for-syntax (displayln (syntax-parameter-value #'current-class)))
> #f
> > (yield 5)
> 5

> syntax (syntax-parameterize ([id expr] ...) body-expr ...+)

> > > See also splicing-syntax-parameterize.

Each id must be bound to a syntax parameter using define-syntax-parameter. Each expr is an expression in the transformer environment. During the expansion of the body-exprs, the value of each expr is bound to the corresponding id.

If an expr produces a procedure of one argument or a make-set!-transformer result, then its id can be used as a macro during the expansion of the body-exprs. If expr produces a make-rename-transformer result, then id can be used as a macro that expands to a use of the target identifier, but syntax-local-value of id does not produce the target’s value.

Examples:

> > (define-syntax-parameter abort (syntax-rules ()))
> > (define-syntax forever
> (syntax-rules ()
> [(forever body ...)
> (call/cc (lambda (abort-k)
> (syntax-parameterize
> ([abort (syntax-rules () [(_) (abort-k)])])
> (let loop () body ... (loop)))))]))
> > (define-syntax-parameter it (syntax-rules ()))
> > (define-syntax aif
> (syntax-rules ()
> [(aif test then else)
> (let ([t test])
> (syntax-parameterize ([it (syntax-id-rules () [_ t])])
> (if t then else)))]))

> syntax (define-rename-transformer-parameter id expr)

Binds id as syntax to a syntax parameter that must be bound to a make-rename-transformer result and, unlike define-syntax-parameter, syntax-local-value of id does produce the target’s value, including inside of syntax-parameterize.

Examples:

> > (define-syntax (test stx)
> (syntax-case stx ()
> [(_ t)
> #`#,(syntax-local-value #'t)]))
> > (define-syntax one 1)
> > (define-syntax two 2)
> > (define-syntax-parameter not-num
> (make-rename-transformer #'one))
> > (test not-num)
> #<procedure:syntax-parameter>
> > (define-rename-transformer-parameter num
> (make-rename-transformer #'one))
> > (test num)
> 1
> > (syntax-parameterize ([num (make-rename-transformer #'two)])
> (test num))
> 2

Added in version 6.3.0.14 of package base.

##### 12.5.1`` Syntax Parameter Inspection

(require racket/stxparam-exptime) | package: base

> procedure (syntax-parameter-value id-stx) → any
> id-stx : syntax?

This procedure is intended for use in a transformer environment, where id-stx is an identifier bound in the normal environment to a syntax parameter. The result is the current value of the syntax parameter, as adjusted by syntax-parameterize form.

This binding is provided for-syntax by racket/stxparam, since it is normally used in a transformer. It is provided normally by racket/stxparam-exptime.

> procedure (make-parameter-rename-transformer id-stx) → any
> id-stx : syntax?

This procedure is intended for use in a transformer, where id-stx is an identifier bound to a syntax parameter. The result is a transformer that behaves as id-stx, but that cannot be used with syntax-parameterize or syntax-parameter-value.

Using make-parameter-rename-transformer is analogous to defining a procedure that calls a parameter. Such a procedure can be exported to others to allow access to the parameter value, but not to change the parameter value. Similarly, make-parameter-rename-transformer allows a syntax parameter to be used as a macro, but not changed.

The result of make-parameter-rename-transformer is not treated specially by syntax-local-value, unlike the result of make-rename-transformer.

This binding is provided for-syntax by racket/stxparam, since it is normally used in a transformer. It is provided normally by racket/stxparam-exptime.

top ← prev up next →