Chapter 5

Modules

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.

A 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 exported with 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 manual. The mzscheme module supplies the initial syntax and variable bindings for a typical module.

Example:

(module hello-world    ; the module name 
        mzscheme       ; initial syntax and variable bindings 
                       ;  for the module body 
  ; the module body 
  (display "Hello world!") 
  (newline))

In general, the initial import serves as a kind of "language" declaration. By initially importing a module other than mzscheme, 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 lambda-calculus language.

5.1  Module Expansion and Execution

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 or require-for-syntax expression at the top level, or a call to dynamic-require.

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.

Example:

(module never-used               ; unused module 
        mzscheme 
  (display "This is never printed") 
  (newline)) 

(module hello-world-printer      ; module used by hello-world2
        mzscheme 
  (define (print-hello-world) 
    (display "Hello world!") 
    (newline)) 
  (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 "Hello world!"

Separating module declarations from module executions benefits compilation in the presence of expressive syntax transformers, as explained in section 12.3.4.

5.2  Module Bodies

In general, the format of a module body depends on the initial import. Since the mzscheme module defines the procedures and syntactic forms described in R5RS and this manual, the body-datums of a module using mzscheme as its initial import must conform to the usual MzScheme top-level grammar.

The 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)

The module-name form imports all exported identifiers from the named module. The (prefix prefix-identifier module-name) form imports all identifiers from the named module, but locally prefixes each identifier with prefix-identifier. The (all-except module-name identifier ···) form imports all identifiers from the named module, except for the listed identifiers. The (prefix-all-except prefix-identifier module-name identifier ···) form combines the prefix and all-except forms. Finally, the (rename module-name local-identifier exported-identifier) imports exported-identifier from module-name, binding it locally to identifier.

The 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 identifier ···)

The identifier form exports the (imported or defined) identifier from the module. The (rename local-identifier export-identifier) form exports local-identifier from the module with the external name export-identifier; other modules importing from this one will see export-identifier instead of local-identifier. The (struct struct-identifier (field-identifier ···)) form exports the names that (define-struct struct-identifier (field-identifier ···)) generates. The (all-from module-name) form exports all of the identifiers imported from the named module, using their local names. The (all-from-except module-name identifier ···) form is similar, except that the listed imported identifiers are not exported. The (all-defined) form exports all of the identifiers defined (not imported) in the module. The (all-defined-except identifier ···) 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. See section 12.3.5 for additional information concerning macro-generated definitions, require declarations, and provide declarations. An identifier can be defined by a definition or import at most once, except than an 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 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.) 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.

Example:

(module a 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 c, prints 8

5.3  Modules and Macros

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.

Example:

(module a 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 2

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.

5.4  Module Paths

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 load, but modules that are intended as libraries have complex interdependencies; constructing an appropriate sequence of load 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 can collide.

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 current-load-relative-directory or current-directory). 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 (file path-string), then 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 current-load-relative-directory or current-directory).

• When a module name has the form (lib filename-string collection-string ···), it specifies a collection-based library; see Chapter 16 for more information about libraries and collections.

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 purposes of provide declarations using all-from and all-from-except, source module paths are compared syntactically (instead of comparing resolved module names).

5.4.1  Module Name Resolver

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 current-module-name-resolver parameter (see also section 7.7.1.12). 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, 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-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 load/use-compiled that passes the expected module name to the load handler.

While loading a file, the standard resolver sets the current-module-name-prefix 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 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 is #f.

5.4.2  Module Names and Compilation

When syntax-expanding or compiling a module declaration, 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.

5.5  Dynamic Module Access

(dynamic-require module-path-v provided-symbol) dynamically invokes the module specified by module-path-v in the current namespace's registry 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. The path is not resolved with respect to any other module, even if the current namespace corresponds to a module body.

If provided-symbol is #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.

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

(dynamic-require-for-syntax module-path-v provided-symbol-or-#f) 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.

5.6  Re-declaring Modules

When a module is re-declared in a namespace whose registry already contains an 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 module->namespace in section 8.3.

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.

If a module was originally declared for a registry via namespace-attach-module, then it cannot be re-declared (and the 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.

5.7  Built-in Modules

The built-in mzscheme 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 module->namespace.

5.8  Modules and Load Handlers

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: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 current-module-name-prefix).

Furthermore, while reading the file and expanding the module declaration, the load handler must set reader parameter values (see section 7.7.1.3) to the following states:

(read-case-sensitive #f)
(read-square-bracket-as-paren #t)
(read-curly-brace-as-paren #t)
(read-accept-box #t)
(read-accept-compiled #t)
(read-accept-bar-quote #t)
(read-accept-graph #t)
(read-decimal-as-inexact #t)
(read-accept-dot #t)
(read-accept-quasiquote #t)

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 #cs (see section 14.3).

Finally, before compiling or evaluating a module declaration from source, the handler must replace a leading module identifier 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 current namespace.

Separate compilation of module declarations introduces the possibility of import cycles when the module declarations are executed. The exn:module exception is raised when such a cycle is detected.