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 declaration consists of the name for the module,
the name of a module to supply an initial set of syntax and variable
bindings, and a module body:
(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 during
the execution of an importing module.
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 form is used both to invoke a module at the
top level, and to import syntax and variables into a module.
(require require-spec ···) require-spec is one of module-name (prefix prefix-identifier module-name) (all-except module-name identifer ···) (prefix-all-except prefix-identifier module-name identifer ···) (rename module-name local-identifer exported-identifer)
module-name form imports all exported identifiers from the
named module. The
( form imports all
identifiers from the named module, but locally prefixes each
( form imports all identifiers from the named
module, except for the listed identifiers. The
form combines the
all-except forms. Finally,
module-name, binding it locally
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 identifer ···) (all-defined) (all-defined-except identifer ···)
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.
The scope of all imported identifiers covers the entire module body,
as does the scope of any identifier defined within the module body.
identifier can be defined by a definition or import at
most once. 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.
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.4 for information on extracting details about an expanded or compiled module declaration.
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 three forms:
unix-relative-path-string (file path-string) (lib filename-string collection-string ···)
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 adject / 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 contain a leading or trailing slash.
When a module name has the form
path-string is interpreted as a file path using the
current platform's path conventions. If
path-string is 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
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 identifer. 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.
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.) The standard module name
resolver also keeps a per-namespace table of loaded module
identifiers. 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
that 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 also called by
namespace-attach-module to notify the resolver that a
module was attached to a namespace (and shouldn't be loaded in the
future). In this notification mode, the first argument to the
#f, the second argument is the name of the
attached module, and the third argument is
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 if it is not yet invoked. If
module-path-v is not a
symbol, the current module name resolver may load a module
declaration to resolve it.
#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, the
exn:application:mismatch 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). The result is void.
) 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
if it is not a symbol.
When a module is re-declared in a namespace (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 namespace essentially maps to a ``sub-namespace'' containing the module's definitions.
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 ``sub-namespace'' consistent with the module declaration.
If a module was originally declared for a namespace via
namespace-attach-module, then it cannot be re-declared (and
exn:module exception is raised if a re-declaration is attempted). If a
module re-declaration creates an import cycle, the
exn:module 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 via
namespace-attach-module, so they cannot be re-declared.
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 ther 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:module 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 18.104.22.168) 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
Separate compilation of
module declarations introduces the
possibility of import cycles when the module declarations are
exn:module exception is raised exception is raised when such a
cycle is detected.