► |  | 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

▼ | 3 | Syntactic Forms

3.1 | Modules: module, module*, ...
3.2 | Importing and Exporting: require and provide
3.3 | Literals: quote and #%datum
3.4 | Expression Wrapper: #%expression
3.5 | Variable References and #%top
3.6 | Locations: #%variable-reference
3.7 | Procedure Applications and #%app
3.8 | Procedure Expressions: lambda and case-lambda
3.9 | Local Binding: let, let*, letrec, ...
3.10 | Local Definitions: local
3.11 | Constructing Graphs: shared
3.12 | Conditionals: if, cond, and, and or
3.13 | Dispatch: case
3.14 | Definitions: define, define-syntax, ...
3.15 | Sequencing: begin, begin0, and begin-for-syntax
3.16 | Guarded Evaluation: when and unless
3.17 | Assignment: set! and set!-values
3.18 | Iterations and Comprehensions: for, for/ list, ...
3.19 | Continuation Marks: with-continuation-mark
3.20 | Quasiquoting: quasiquote, unquote, and unquote-splicing
3.21 | Syntax Quoting: quote-syntax
3.22 | Interaction Wrapper: #%top-interaction
3.23 | Blocks: block
3.24 | Internal-Definition Limiting: #%stratified-body
3.25 | Performance Hints: begin-encourage-inline
3.26 | Importing Modules Lazily: lazy-require

► | 3.14 | Definitions: define, define-syntax, ...

3.14.1 | require Macros
3.14.2 | provide Macros

On this page:

define
define-values
define-syntax
define-syntaxes
define-for-syntax
define-values-for-syntax
3.14.1`` require Macros
define-require-syntax
syntax-local-require-introduce
3.14.2`` provide Macros
define-provide-syntax
syntax-local-provide-introduce

top ← prev up next →

#### 3.14`` Definitions: define, define-syntax, ...

> > > Definitions: define in The Racket Guide introduces definitions.

> syntax (define id expr)
> (define (head args) body ...+)
> head |  | = |  | id
> |  | | |  | (head args)
> args |  | = |  | arg ...
> |  | | |  | arg ... . rest-id
> arg |  | = |  | arg-id
> |  | | |  | [arg-id default-expr]
> |  | | |  | keyword arg-id
> |  | | |  | keyword [arg-id default-expr]

The first form binds id to the result of expr, and the second form binds id to a procedure. In the second case, the generated procedure is (CVT (head args) body ...+), using the CVT meta-function defined as follows:

> (CVT (id . kw-formals) . datum) = (lambda kw-formals . datum)
> (CVT (head . kw-formals) . datum) = (lambda kw-formals expr)
> if (CVT head . datum) = expr

In an internal-definition context, a define form introduces a local binding; see Internal Definitions. At the top level, the top-level binding for id is created after evaluating expr, if it does not exist already, and the top-level mapping of id (in the namespace linked with the compiled definition) is set to the binding at the same time.

In a context that allows liberal expansion of define, id is bound as syntax if expr is an immediate lambda form with keyword arguments or args include keyword arguments.

Examples:

> (define x 10)
> > x
> 10
> (define (f x)
> (+ x 1))
> > (f 10)
> 11
> (define ((f x) [y 20])
> (+ x y))
> > ((f 10) 30)
> 40
> > ((f 10))
> 30

> syntax (define-values (id ...) expr)

Evaluates the expr, and binds the results to the ids, in order, if the number of results matches the number of ids; if expr produces a different number of results, the exn:fail:contract exception is raised.

In an internal-definition context (see Internal Definitions), a define-values form introduces local bindings. At the top level, the top-level binding for each id is created after evaluating expr, if it does not exist already, and the top-level mapping of each id (in the namespace linked with the compiled definition) is set to the binding at the same time.

Examples:

> > (define-values () (values))
> > (define-values (x y z) (values 1 2 3))
> > z
> 3

If a define-values form for a function definition in a module body has a 'compiler-hint:cross-module-inline syntax property with a true value, then the Racket treats the property as a performance hint. See Function-Call Optimizations in The Racket Guide for more information, and see also begin-encourage-inline.

> syntax (define-syntax id expr)
> (define-syntax (head args) body ...+)

The first form creates a transformer binding (see Transformer Bindings) of id with the value of expr, which is an expression at phase level 1 relative to the surrounding context. (See Identifiers, Binding, and Scopes for information on phase levels.) Evaluation of expr side is parameterized to set current-namespace as in let-syntax.

The second form is a shorthand the same as for define; it expands to a definition of the first form where the expr is a lambda form.

In an internal-definition context (see Internal Definitions), a define-syntax form introduces a local binding.

Examples:

> > (define-syntax foo
> (syntax-rules ()
> ((_ a ...)
> (printf "~a\n" (list a ...)))))
> > (foo 1 2 3 4)
> (1 2 3 4)
> > (define-syntax (bar syntax-object)
> (syntax-case syntax-object ()
> ((_ a ...)
> #'(printf "~a\n" (list a ...)))))
> > (bar 1 2 3 4)
> (1 2 3 4)

> syntax (define-syntaxes (id ...) expr)

Like define-syntax, but creates a transformer binding for each id. The expr should produce as many values as ids, and each value is bound to the corresponding id.

When expr produces zero values for a top-level define-syntaxes (i.e., not in a module or internal-definition position), then the ids are effectively declared without binding; see Macro-Introduced Bindings.

In an internal-definition context (see Internal Definitions), a define-syntaxes form introduces local bindings.

Examples:

> > (define-syntaxes (foo1 foo2 foo3)
> (let ([transformer1 (lambda (syntax-object)
> (syntax-case syntax-object ()
> [(_) #'1]))]
> [transformer2 (lambda (syntax-object)
> (syntax-case syntax-object ()
> [(_) #'2]))]
> [transformer3 (lambda (syntax-object)
> (syntax-case syntax-object ()
> [(_) #'3]))])
> (values transformer1
> transformer2
> transformer3)))
> > (foo1)
> 1
> > (foo2)
> 2
> > (foo3)
> 3

> syntax (define-for-syntax id expr)
> (define-for-syntax (head args) body ...+)

Like define, except that the binding is at phase level 1 instead of phase level 0 relative to its context. The expression for the binding is also at phase level 1. (See Identifiers, Binding, and Scopes for information on phase levels.) The form is a shorthand for (begin-for-syntax (define id expr)) or (begin-for-syntax (define (head args) body ...+)).

Within a module, bindings introduced by define-for-syntax must appear before their uses or in the same define-for-syntax form (i.e., the define-for-syntax form must be expanded before the use is expanded). In particular, mutually recursive functions bound by define-for-syntax must be defined by the same define-for-syntax form.

Examples:

> > (define-for-syntax helper 2)
> > (define-syntax (make-two syntax-object)
> (printf "helper is ~a\n" helper)
> #'2)
> > (make-two)
> helper is 2
> 2
> ; ‘helper' is not bound in the runtime phase
> > helper
> helper: undefined;
> cannot reference undefined identifier
> > (define-for-syntax (filter-ids ids)
> (filter identifier? ids))
> > (define-syntax (show-variables syntax-object)
> (syntax-case syntax-object ()
> [(_ expr ...)
> (with-syntax ([(only-ids ...)
> (filter-ids (syntax->list #'(expr ...)))])
> #'(list only-ids ...))]))
> > (let ([a 1] [b 2] [c 3])
> (show-variables a 5 2 b c))
> '(1 2 3)

> syntax (define-values-for-syntax (id ...) expr)

Like define-for-syntax, but expr must produce as many values as supplied ids, and all of the ids are bound (at phase level 1).

Examples:

> > (define-values-for-syntax (foo1 foo2) (values 1 2))
> > (define-syntax (bar syntax-object)
> (printf "foo1 is ~a foo2 is ~a\n" foo1 foo2)
> #'2)
> > (bar)
> foo1 is 1 foo2 is 2
> 2

##### 3.14.1`` require Macros

(require racket/require-syntax) | package: base

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

> syntax (define-require-syntax id proc-expr)
> (define-require-syntax (id args ...) body ...+)

The first form is like define-syntax, but for a require sub-form. The proc-expr must produce a procedure that accepts and returns a syntax object representing a require sub-form.

This form expands to define-syntax with a use of make-require-transformer (see require Transformers for more information), and the syntax object passed to and from the macro transformer is adjusted via syntax-local-require-introduce.

The second form is a shorthand the same as for define-syntax; it expands to a definition of the first form where the proc-expr is a lambda form.

> procedure (syntax-local-require-introduce stx) → syntax?
> stx : syntax?

Provided for-syntax for use only during the application of a require sub-form macro transformer: like syntax-local-introduce, but for require sub-form expansion.

##### 3.14.2`` provide Macros

(require racket/provide-syntax) | package: base

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

> syntax (define-provide-syntax id proc-expr)
> (define-provide-syntax (id args ...) body ...+)

The first form is like define-syntax, but for a provide sub-form. The proc-expr must produce a procedure that accepts and returns a syntax object representing a provide sub-form.

This form expands to define-syntax with a use of make-provide-transformer (see provide Transformers for more information), and the syntax object passed to and from the macro transformer is adjusted via syntax-local-provide-introduce.

The second form is a shorthand the same as for define-syntax; it expands to a definition of the first form where the expr is a lambda form.

> procedure (syntax-local-provide-introduce stx) → syntax?
> stx : syntax?

Provided for-syntax for use only during the application of a provide sub-form macro transformer: like syntax-local-introduce, but for provide sub-form expansion.
top ← prev up next →