2.1 Modules: module, module*, ...

► |  | The Racket Reference

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

▼ | 2 | Syntactic Forms

2.1 | Modules: module, module*, ...
2.2 | Importing and Exporting: require and provide
2.3 | Literals: quote and #%datum
2.4 | Expression Wrapper: #%expression
2.5 | Variable References and #%top
2.6 | Locations: #%variable-reference
2.7 | Procedure Applications and #%app
2.8 | Procedure Expressions: lambda and case-lambda
2.9 | Local Binding: let, let*, letrec, ...
2.10 | Local Definitions: local
2.11 | Constructing Graphs: shared
2.12 | Conditionals: if, cond, and, and or
2.13 | Dispatch: case
2.14 | Definitions: define, define-syntax, ...
2.15 | Sequencing: begin, begin0, and begin-for-syntax
2.16 | Guarded Evaluation: when and unless
2.17 | Assignment: set! and set!-values
2.18 | Iterations and Comprehensions: for, for/ list, ...
2.19 | Continuation Marks: with-continuation-mark
2.20 | Quasiquoting: quasiquote, unquote, and unquote-splicing
2.21 | Syntax Quoting: quote-syntax
2.22 | Interaction Wrapper: #%top-interaction
2.23 | Blocks: block
2.24 | Internal-Definition Limiting: #%stratified-body
2.25 | Performance Hints: begin-encourage-inline
2.26 | Importing Modules Lazily: lazy-require

On this page:

module
module*
module+
#%module-begin
#%plain-module-begin

top ← prev up next →

#### 2.1`` Modules: module, module*, ...

> > > The module Form in The Racket Guide introduces module.

> syntax (module id module-path form ...)

Declares a top-level module or a submodule. For a top-level module, if the current-module-declare-name parameter is set, the parameter value is used for the module name and id is ignored, otherwise (quote id) is the name of the declared module. For a submodule, id is the name of the submodule to be used as an element within a submod module path.

> > > For a module-like form that works in definitions context other than the top level or a module body, see define-package.

The module-path form must be as for require, and it supplies the initial bindings for the body forms. That is, it is treated like a (require module-path) prefix before the forms, except that the bindings introduced by module-path can be shadowed by definitions and requires in the module body forms.

If a single form is provided, then it is partially expanded in a module-begin context. If the expansion leads to #%plain-module-begin, then the body of the #%plain-module-begin is the body of the module. If partial expansion leads to any other primitive form, then the form is wrapped with #%module-begin using the lexical context of the module body; this identifier must be bound by the initial module-path import, and its expansion must produce a #%plain-module-begin to supply the module body. Finally, if multiple forms are provided, they are wrapped with #%module-begin, as in the case where a single form does not expand to #%plain-module-begin.

After such wrapping, if any, and before any expansion, an 'enclosing-module-name property is attached to the #%module-begin syntax object (see Syntax Object Properties); the property’s value is a symbol corresponding to id.

Each form is partially expanded (see Partial Expansion) in a module context. Further action depends on the shape of the form:

- If it is a begin form, the sub-forms are flattened out into the module’s body and immediately processed in place of the begin.

- If it is a define-syntaxes form, then the right-hand side is evaluated (in phase 1), and the binding is immediately installed for further partial expansion within the module. Evaluation of the right-hand side is parameterized to set current-namespace as in let-syntax.

- If it is a begin-for-syntax form, then the body is expanded (in phase 1) and evaluated. Expansion within a begin-for-syntax form proceeds with the same partial-expansion process as for a module body, but in a higher phase, and saving all #%provide forms for all phases until the end of the module’s expansion. Evaluation of the body is parameterized to set current-namespace as in let-syntax.

- If the form is a #%require form, bindings are introduced immediately, and the imported modules are instantiated or visited as appropriate.

- If the form is a #%provide form, then it is recorded for processing after the rest of the body.

- If the form is a define-values form, then the binding is installed immediately, but the right-hand expression is not expanded further.

- If the form is a module form, then it is immediately expanded and declared for the extent of the current top-level enclosing module’s expansion.

- If the form is a module* form, then it is not expanded further.

- Similarly, if the form is an expression, it is not expanded further.

After all forms have been partially expanded this way, then the remaining expression forms (including those on the right-hand side of a definition) are expanded in an expression context. After all expression forms, #%provide forms are processed in the order in which they appear (independent of phase) in the expanded module. Finally, all module* forms are expanded in order, so that each becomes available for use by subsequent module* forms; the enclosing module itself is also available for use by module* submodules.

The scope of all imported identifiers covers the entire module body, except for nested module and module* forms (assuming a non-#f module-path in the latter case). The scope of any identifier defined within the module body similarly covers the entire module body except for such nested module and module* forms. The ordering of syntax definitions does not affect the scope of the syntax names; a transformer for A can produce expressions containing B, while the transformer for B produces expressions containing A, regardless of the order of declarations for A and B. However, a syntactic form that produces syntax definitions must be defined before it is used.

No identifier can be imported or defined more than once at any phase level within a single module. Every exported identifier must be imported or defined. No expression can refer to a top-level variable. A module* form in which the enclosing module’s bindings are visible (i.e., a nested module* with #f instead of a module-path) can define or import bindings that shadow the enclosing module’s bindings.

The evaluation of a module form does not evaluate the expressions in the body of the module. Evaluation merely declares a module, whose full name depends both on id or (current-module-declare-name).

A module body is executed only when the module is explicitly instantiated via require or dynamic-require. On invocation, imported modules are instantiated in the order in which they are required into the module (although earlier instantiations or transitive requires can trigger the instantiation of a module before its order within a given module). Then, expressions and definitions are evaluated in order as they appear within the module. Each evaluation of an expression or definition is wrapped with a continuation prompt (see call-with-continuation-prompt) for the default continuation and using a prompt handler that re-aborts and propagates its argument to the next enclosing prompt.

Accessing a module-level variable before it is defined signals a run-time error, just like accessing an undefined global variable. If a module (in its fully expanded form) does not contain a set! for an identifier that defined within the module, then the identifier is a constant after it is defined; its value cannot be changed afterward, not even through reflective mechanisms. The compile-enforce-module-constants parameter, however, can be used to disable enforcement of constants.

When a syntax object representing a module form has a 'module-language syntax property attached, and when the property value is a vector of three elements where the first is a module path (in the sense of module-path?) and the second is a symbol, then the property value is preserved in the corresponding compiled and/or declared module. The third component of the vector should be printable and readable, so that it can be preserved in marshaled bytecode. The racket/base and racket languages attach '#(racket/language-info get-info #f) to a module form. See also module-compiled-language-info, module->language-info, and racket/language-info.

If a module form has a single body form and if the form is a #%plain-module-begin form, then the body form is traversed to find module and module* forms that are either immediate, under begin, or under begin-for-syntax. (That is, the body is searched before adding any lexical context due to the module’s initial module-path import.) Each such module form is given a 'submodule syntax property that whose value is the initial module form. Then, when module or module* is expanded in a submodule position, if the form has a 'submodule syntax property, the property value is used as the form to expand. This protocol avoids the contamination of submodule lexical scope when re-expanding module forms that contain submodules.

See also Modules and Module-Level Variables and Module Phases and Visits.

Example:
> > (module duck racket/base
> (provide num-eggs quack)
> (define num-eggs 2)
> (define (quack n)
> (unless (zero? n)
> (printf "quack\n")
> (quack (sub1 n)))))

> syntax (module* id module-path form ...)
> (module* id #f form ...)

> > > Submodules in The Racket Guide introduces module*.

Like module, but only for declaring a submodule within a module, and for submodules that may require the enclosing module.

Instead of a module-path after id, #f indicates that all bindings from the enclosing module are visible in the submodule; begin-for-syntax forms that wrap the module* form shift the phase level of the enclosing module’s bindings relative to the submodule. When a module* form has a module-path, the submodule starts with an empty lexical context in the same way as a top-level module form, and enclosing begin-for-syntax forms have no effect on the submodule.

> syntax (module+ id form ...)

> > > Main and Test Submodules in The Racket Guide introduces module+.

Declares and/or adds to a submodule named id.

Each addition for id is combined in order to form the entire submodule using (module* id #f ....) at the end of the enclosing module. If there is only one module+ for a given id, then (module+ id form ...) is equivalent to (module* id #f form ...).

A submodule must not be defined using module+ and module or module*. That is, if a submodule is made of module+ pieces, then it must be made only of module+ pieces.

> syntax (#%module-begin form ...)

Legal only in a module begin context, and handled by the module and module* forms.

The #%module-begin form of racket/base wraps every top-level expression to print non-#<void> results using current-print.

> syntax (#%plain-module-begin form ...)

Legal only in a module begin context, and handled by the module and module* forms.
top ← prev up next →