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 (see Internal Definitions), a define form introduces a local binding. 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 and Binding 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 and Binding 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 marked 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 marked 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 →

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