MzScheme provides a module system for managing the scope of variable and syntax definitions, and for directing compilation. Module declarations can appear only at the top level. The space of module names is separate from the space of top-level variable and syntax names.
(module module-identifier initial-required-module-name body-datum ···)
A module encapsulates syntax definitions to be used in expanding the
body of the module, as well as expressions and definitions to be
evaluated when the module is executed. When a syntax identifier is
provide (as described in section 5.2),
its transformer can be used during the expansion of an importing
module; when a variable identifier is exported, its value can be used
(but not assigned with
set!) during the execution of an
A module named
mzscheme is built in, and it exports the
procedures and syntactic forms described in R5RS and this
module supplies the initial syntax and
variable bindings for a typical module.
(module hello-world ; the module name
mzscheme; initial syntax and variable bindings ; for the module body ; the module body (
display"Hello world!") (
In general, the initial import serves as a kind of "language"
declaration. By initially importing a module other than
, a module can be defined in terms of a commonly-used
variant of Scheme that contains more than the MzScheme built-in
syntax and procedures, or a variant of Scheme that contains fewer
constructs. The initial import might even omit syntax for declaring
additional imports. For example, section 12.5 shows an
example module that defines a
When a module declaration is evaluated, the module's body is
syntax-expanded and compiled, but not executed. The body is executed
only when the module is explicitly invoked, via a
require-for-syntax expression at the top level, or a call to
When a module is invoked, its body definitions and expressions are
evaluated. First, however, the definitions and expressions are
evaluated for each module imported (via
require) by the
invoked module. The import-initialization rule applies up the chain
of modules, so that every module used (directly or indirectly) by the
invoked module is executed before any module that uses its exports. A
module can only import from previously declared modules, so the
module-import relationship is acyclic.
Every module is executed at most once in response to an invocation, regardless of the number of times it is imported into other modules. Every top-level invocation executes only the modules needed by the invocation that have not been executed by previous invocations.
(module never-used ; unused module
display"This is never printed") (
newline)) (module hello-world-printer ; module used by
mzscheme(define (print-hello-world) (
display"Hello world!") (
display"printer ready") (
newline) (provide print-hello-world)) ; export (module hello-world2
mzscheme; initial import (require hello-world-printer) ; additional import (print-hello-world)) (require hello-world2) ; => prints
"printer ready", then
Separating module declarations from module executions benefits compilation in the presence of expressive syntax transformers, as explained in section 12.3.4.
In general, the format of a module body depends on the initial
import. Since the
module defines the procedures and
syntactic forms described in R5RS and this manual, the
body-datums of a module using
as its initial
import must conform to the usual MzScheme top-level grammar.
(require require-spec ···) require-spec is one of module-name (only module-name identifier ···) (prefix prefix-identifier module-name) (all-except module-name identifier ···) (prefix-all-except prefix-identifier module-name identifier ···) (rename module-name local-identifier exported-identifier)
module-name form imports all exported identifiers from the
form imports only the listed identifiers from the named module.
form imports all identifiers from the named module, but locally
prefixes each identifier with
form imports all identifiers from the named module, except for the
form combines the
all-except forms. Finally,
module-name, binding it
provide form (legal only within a module declaration)
exports syntax and variable bindings from the current module for use
by other modules. The exported identifiers must be either defined or
imported in the module, but the export of an identifier may precede
its definition or import.
(provide provide-spec ···) provide-spec is one of identifier (rename local-identifier export-identifier) (struct struct-identifier (field-identifier ···)) (all-from module-name) (all-from-except module-name identifier ···) (all-defined) (all-defined-except identifier ···) (prefix-all-defined prefix-identifier) (prefix-all-defined-except prefix-identifier identifier ···) (protect provide-spec ···)
identifier form exports the (imported or defined) identifier
from the module.
( form exports
local-identifier from the module with the external name
export-identifier; other modules importing from this one will
export-identifier instead of
( form exports the names that
(define-struct struct-identifier (field-identifier ···))
form exports all of the identifiers imported from the named module,
using their local names.
( form is similar, except
that the listed imported identifiers are not exported.
( form exports
all of the identifiers defined (not imported) in the module.
( form is similar, except that the listed
defined identifiers are not exported.
forms are like
is prefixed onto each defined identifier for its external name.
( form is like the sequence of individual
but the provided identifiers are protected (see section 9.4);
provide-specs must not contain another
all-from form, or an
all-from-except form, and they
must not name any identifier that is imported into the providing
module, instead of defined within the module.
The scope of all imported identifiers covers the entire module body,
as does the scope of any identifier defined within the module body.
See section 12.3.5 for additional information concerning
provide declarations. An
identifier can be
defined by a definition or import at most once, except than
identifier can be imported multiple times if each import is
from the same module. All exports must be unique. A module body
cannot contain free variables. A module is not permitted to mutate
an imported variable with
set!. However, mutations to an
exported variable performed by its defining module are visible to
modules that import the variable.
At syntax-expansion time, expressions and definitions within a module
are partially expanded, just enough to determine whether the
expression is a definition, syntax definition, import, export, or a
non-definition. If a partially expanded expression is a syntax
definition, the syntax transformer is immediately evaluated and the
syntax name is available for expanding successive expressions. Import
expressions are treated similarly, so that imported syntax is
available for expansion following its import. (The ordering of syntax
definitions does not affect the scope of the syntax names; a
A can produce expressions containing
B, while the transformer for
B produces expressions
A, regardless of the order of declarations for
B. However, a syntactic form that produces
syntax definitions must be defined before it is used.) The
begin form at the top level for a module body works like
begin at the top level, so that the sub-expressions are
flattened out into the module's body.
At run time, expressions and definitions are evaluated in order as they appear within the module. Accessing a (non-syntax) identifier before it is initialized signals a run-time error, just like accessing an undefined global variable.
mzscheme(provide x) (define x 1)) (module b
mzscheme(provide f (rename x y)) (define x 2) (define (f) (set! x 7))) (module c
mzscheme(require (prefix a. a) (prefix b. b)) (b.f) (
display(+ a.x b.y)) (
newline)) (require c) ; => executes
Macros defined with
syntax-rules follow the rules specified
in R5RS regarding the binding and free references in the macro
template. In particular, the template of an exported macro may refer
to an identifier defined in the module or imported into the module;
uses of the macro in other modules expand to references of the
identifier defined or imported at the macro-definition site, as
opposed to the use site. Uses of a macro in a module must not expand
set! assignment of an identifier from any other module
(including the module that defines the macro).
mzscheme(provide xm) (define y 2) (define-syntax xm ; a macro that expands to
y(syntax-rules () [(xm) y]))) (module b
mzscheme(require a) (
printf"~a~n" (xm))) (require b) ; => prints
For further information about syntax definitions, see section 12.3.4. See section 12.6.5 for information on extracting details about an expanded or compiled module declaration. See section 9.4 for information on how unexported and protected identifiers in a macro expansion are constrained to their macro-introduced contexts.
In practice, the modules composing a program are rarely declared
together in a single file. Multiple module-declaring files can be
loaded in sequence with
, but modules that are intended as
libraries have complex interdependencies; constructing an appropriate
expressions -- one that loads each module
declaration exactly once and before all of its uses -- can be
difficult and tedious. Worse, even though module declarations prevent
collisions among syntax and variable names, module names themselves
To solve these problems, a
module-name can describe a path to a
module source file, which is resolved by the current module
name resolver. The default module name resolver loads the source for
a given module path the first time that the source is referenced. To
avoid module name collisions, the module in the referenced file is
assigned a name that identifies its source file.
A module path resolved by the standard resolver can take any of four forms:
unix-relative-path-string (file path-string) (lib filename-string collection-string ···) (planet . datum) path
When a module name is a string,
unix-relative-path-string, it is interpreted as a path relative to the source of the containing module (as determined by
). Regardless of the platform running MzScheme, the path is always parsed as a Unix-format path: / is the path delimiter (multiple adjacent / are treated as a single delimiter), .. accesses the parent directory, and . accesses the current directory. To avoid portability problems, the path elements are further constrained to contain only alpha-numeric characters plus -, _, ., and space, and the path may not be empty or contain a leading or trailing slash.
When a module name has the form
path-stringis interpreted as a file path using the current platform's path conventions. If
path-stringis a relative path, it is resolved relative to the source of the containing module (as determined by
When a module name has the form
(, it specifies a collection-based library; see Chapter 16 for more information about libraries and collections.
When a module name has the form
(, it is passed to the PLaneT resolver as described in section 5.4.1.
Since path values (see section 11.3.1) cannot be written as literal syntax, a
pathnever appear in
requireforms. However, an absolute path value may be passed to
dynamic-require, and it is treated in the same way as a
A source file that is referenced by a module path must contain a single module declaration. The name of the declared module must match the source's filename, minus its suffix.
Different module paths can access the same module, but for the
provide declarations using
all-from-except, source module paths are compared
syntactically (instead of comparing resolved module names).
In general, the module name resolver is invoked by MzScheme when a
module-name is not an identifier. The grammar of non-symbolic
module names is determined by the module name resolver. The module
name resolver, in turn, is determined by the
parameter (see also
section 220.127.116.11). The resolver is a function
that takes three arguments -- an arbitrary value for the module
path, a symbol for the source module's name, and a syntax object or
#f -- and returns a symbol for the resolved name.
(planet . datum) paths (which are handled as
described below), the standard module name resolver creates a module
identifier as the expanded, simplified, case-normalized, and
de-suffixed path of the file designated by the module path. (See
section 11.3 for details on platform-specific path handling.)
To better support
dynamic-require, the standard module name
resolver accepts a path object (see section 11.3.1) and treats it
file module path.
The standard module name resolver keeps a per-registry table of loaded
module identifiers (where the registry is obtained from a namespace;
see Chapter 8). If the resolved identifier is not in the
table, the identifier is put into the table and the corresponding
file is loaded with a variant of
passes the expected module name to the load handler.
While loading a file, the standard resolver sets the
parameter, so that the name of
any module declared in the loaded file is given a prefix. This
mechanism enables the resolver to avoid module name collisions. The
resolver sets the prefix to the resolved module name, minus the
de-suffixed file name. It also loads the file by calling the load
handler or load extension handler with the name of the expected
module (see section 5.8).
The current module name resolver is called by
namespace-attach-module to notify the resolver that a
module was attached to the current namespace (and shouldn't be loaded
in the future for the namespace's registry). In this notification
mode, the first argument to the resolver is
#f, the second
argument is the name of the attached module, and the third argument
When the default module name resolver is given a module path of the
(planet . datum) as its first argument, it provides
all of the resolver arguments to the PLaneT resolver. If the PLaneT
resolver has not yet been loaded, it is loaded in the initial
namespace by requiring
(lib "resolver.ss" "planet"). Thereafter, the PLaneT
resolver receives each
that the standard resolver receives.
When syntax-expanding or compiling a
MzScheme resolves module names for imports (since some imported
identifier may have syntax bindings), but it also preserves the
module path name. Consequently, a compiled module can be moved to
another filesystem, where the module name resolver can resolve
inter-module references among compiled code.
invokes the module specified by
module-path-v in the current
namespace's registry if it is not yet invoked. If
is not a symbol, the current module name resolver may load a module
declaration to resolve it. For example, the default module-name
resolver accepts a path value as
module-path-v. The path is not
resolved with respect to any other module, even if the current
namespace corresponds to a module body.
#f, then the result is
void. Otherwise, when
provided-symbol is a symbol, the
value of the module's export with the given name is returned. If the
module has no such exported variable or if the variable is protected
(see section 9.4), the
exn:fail:contract exception is raised. The
expansion-time portion of the module is not executed.
provided-symbol is void, then the module is partially
invoked, where its expansion-time expressions are evaluated, but not
its normal expressions (though the module may have been invoked
previously in the current namespace's registry). The result is
) is similar to
dynamic-require, except that it accesses a value from an
expansion-time module instance (the one that could be used by
transformers in expanding top-level expressions in the current
namespace). As with
dynamic-require, the module
name resolver may load a module declaration to resolve
module-path-v if it is not a symbol.
When a module is re-declared in a namespace whose registry already
contains a declaration of the module (see Chapter 8), the
new declaration's syntax and variable definitions replace and extend
the old declarations. If a variable in the old declaration has no
counterpart in the new declaration, it continues to exist, but
becomes inaccessible to newly compiled code. In other words, a module
name in a particular registry maps to a namespace containing the
module body's definitions; see also
If a module is invoked before it is re-declared, each re-declaration of the module is immediately invoked. The immediate invocation is necessary to keep the module-specific namespace consistent with the module declaration.
A module can only be redeclared when the current code inspector -- as
determined by the
section 18.104.22.168) -- controls the invocation of the
module in the current namespace's registry. If the current code
inspector does not control the invocation at the time of a
re-declaration attempt, the
exn:fail:contract exception is raised. If a module
re-declaration would create an import cycle, the
exn:fail:contract exception is raised.
module is implemented by several
primitive modules whose names start with
#%. In general,
module names starting with
#% are reserved for use by
MzScheme and embedding applications. The built-in modules are
declared in the initial namespace's registry via
namespace-attach-module, so they cannot be re-declared and
their private namespaces are not available via
The second argument to a load handler or load extension handler
indicates whether the load is expected (and required) to produce a
module declaration. If the second argument is
#f, the file
is loaded normally, otherwise the argument will be a symbol and the
file must be checked specially before it is loaded.
When the second argument to the local handler is a symbol, the handler
is responsible for ensuring that the file-to-load actually contains a
module declaration (possibly compiled); if not, it must
raise an exception without evaluating the declaration. The handler
must also raise an
exn:fail exception if the name in the
module declaration is not the same as the symbol argument to the
handler (before applying any prefix in
Furthermore, while reading the file and expanding the module declaration, the load handler must set reader parameter values (see section 22.214.171.124) to the following states:
These states are the same as the normal defaults, except that
compiled-code reading is enabled. Note that a module body can be made
case sensitive by prefixing the module with
Finally, before compiling or evaluating a module declaration from
source, the handler must replace a leading
with an identifier that is bound to the
module export of
MzScheme. Evaluating the expression will then produce a module
declaration, regardless of the binding of
module in the