#
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-datum`s 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-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 ``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 a namespace (and shouldn't be loaded in the future). 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 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.

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). 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 (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 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 via `namespace-attach-module`, so they cannot be re-declared.

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