### Modules

To allow some control over visible bindings and to organize code at the global level, a simple module system is available. A module defines a set of toplevel expressions that are initially evaluated in an empty syntactical environment. By importing other modules, exported value- and macro-bindings are made visible inside the environment of the module that imports them.

Note that modules are purely syntactical - they do not change the control flow or delay the execution of the contained toplevel forms. The body of a module is executed at load-time, when code is loaded or accessed via the `uses` declaration, just like normal toplevel expressions. Exported macro-definitions are compiled as well, and can be accessed in interpreted or compiled code by loading and importing the compiled file that contains the module.

Imported toplevel bindings can be assigned (with `set!`), any modifications to these will change the global value and will be visible to other modules that export or import the same toplevel binding.

A module is initially empty (has no visible bindings). You must at least import the `scheme` module to do anything useful. To access any of the non-standard macros and procedures, import the `chicken` module.

CHICKEN's module system has the following features and shortcomings:

- Indirect exports for syntax definitions must be listed
- Separation of compile/expansion-time and run-time code is provided, which allows cross compilation
- Module-generating code is only created, when needed
- Supports batch-compilation of separate compilation units
- No separate "identifier" type is used, all identifiers appearing in code and processed in expansions are symbols
- The module system is fully optional

#### module

`(module NAME (EXPORT ...) BODY ...)` syntax
`(module NAME (EXPORT ...) FILENAME)` syntax
`(module NAME * BODY ...)` syntax

  Defines a module with the name `NAME`, a set of exported bindings and a contained sequence of toplevel expressions that are evaluated in an empty syntactical environment. `EXPORT` may be a symbol or a list of the form `(IDENTIFIER1 IDENTIFIER2 ...)`. In the former case the identifier given is exported from the module and can be imported at the toplevel or in other modules. The latter case exports `IDENTIFIER1` (which should name a macro) and also arranges for the remaining identifiers in the list to be visible in the expansion of the macro (this is a hint to the module expander to export bindings referenced by syntax-definitions which make use of them, but which would normally be internal to the module - which gives more opportunities for optimization).

  When the `BODY` consists of a single string, it is handled as `(include FILENAME)`.

  Nested modules, modules not at toplevel (i.e. local modules) or mutually recursive modules are not supported.

  When compiled, the module information, including exported macros is stored in the generated binary and available when loading it into interpreted or compiled code. Note that this is different to normal macros (outside of module declarations), which are normally not exported from compiled code.

  As a special case, specifying `*` instead of an export-list will export all definitions.

  Note that the module system is only a device for controlling the mapping of identifiers to value or syntax bindings. Modules do not instantiate separate environments that contain their own bindings, as do many other module systems. Redefinition or assignment of value or syntax bindings will modify the original, imported definition.

  Syntax expansions may result in module-definitions, but must be at toplevel.

#### export

`(export EXPORT ...)` syntax

  Allows augmenting module-exports from inside the module-body. `EXPORT` is if the same form as an export-specifier in a `module` export list. An export must precede its first occurrence (either use or definition).

  If used outside of a module, then this form does nothing.

#### import

`(import IMPORT ...)` syntax

  Imports module bindings into the current syntactical environment. The visibility of any imported bindings is limited to the current module, if used inside a module-definition, or to the current compilation unit, if compiled and used outside of a module.

  Importing a module does not load or link it - this is a separate operation from importing its bindings.

  `IMPORT` may be a module name or an import specifier, where a module name is either a symbol or a list of the form `(srfi N)`. An `IMPORT` defines a set of bindings that are to be made visible in the current scope.

  Note that the imported bindings are only visible in the next toplevel expression (regardless of whether the import appears inside or outside a module):

       (begin
         (import m1)
         ...)              ; imports not visible here

       ...                ; imports visible here

##### only

    [import specifier] (only IMPORT IDENTIFIER ...)

Only import the listed value- or syntax bindings from the set given by `IMPORT`.

##### except

    [import specifier] (except IMPORT IDENTIFIER ...)

Remove the listed identifiers from the import-set defined by `IMPORT`.

##### rename

    [import specifier] (rename IMPORT (OLD1 NEW1) ...)

Renames identifiers imported from `IMPORT`.

##### prefix

    [import specifier] (prefix IMPORT SYMBOL)

Prefixes all imported identifiers with `SYMBOL`.

#### import-for-syntax

`(import-for-syntax IMPORT ...)` syntax

  Similar to `import`, but imports exported bindings of a module into the environment in which macro transformers are evaluated.

  Note: currently this isn't fully correct - value bindings are still imported into the normal environment because a separate import environment for syntax has not been implemented (syntactic bindings are kept separate correctly).

#### reexport

`(reexport IMPORT ...)` syntax

  Imports `IMPORT ...` and automatically exports all imported identifiers. This can be used to build compound modules: modules that just extend other modules:

      (module r4rs ()
        (import scheme chicken)
        (reexport
          (except scheme
            dynamic-wind values call-with-values eval scheme-report-environment
            null-environment interaction-environment)))

### import libraries

import libraries allow the syntactical (compile-time) and run-time parts of a compiled module to be separated into a normal compiled file and a shared library that only contains macro definitions and module information. This reduces the size of executables and simplifies compiling code that uses modules for a different architecture than the machine the compiler is executing on (i.e. "cross" compilation).

By using the `emit-import-library` compiler-option or declaration, a separate file is generated that only contains syntactical information (including macros) for a module. `import` will automatically find and load an import library for a currently unknown module, if the import- library is either in the extension repository or the current include path. Import libraries may also be explicitly loaded into the compiler by using the `-extend` compiler option. Interpreted code can simply load the import library to make the module-definition available. Macro-support definitions defined with `define-for-syntax` and expansion-time expressions of the form `(begin-for-syntax ...)` will be added to import libraries to make them available for exported macros. Note that these definitions will ruthlessly pollute the toplevel namespace and so they should be used sparingly.

### Predefined modules

Import libraries for the following modules are initially available:

    [module] scheme

Exports the standard R5RS bindings.

    [module] chicken

Everything from the `library`, `eval` and `expand` library units.

    [module] extras
    [module] data-structures
    [module] ports
    [module] lolevel
    [module] posix
    [module] regex
    [module] srfi-1
    [module] srfi-4
    [module] srfi-13
    [module] srfi-14
    [module] srfi-18
    [module] srfi-69
    [module] tcp
    [module] utils

Modules exporting the bindings from the respective library units.

    [module] foreign

Exports all macros and procedures that are used to access foreign C/C++ code.

### Examples of using modules

Here is a silly little test module to demonstrate how modules are defined and used:

    ;; hello.scm

    (module test (hello greet)
      (import scheme)

      (define-syntax greet
        (syntax-rules ()
          ((_ whom)
           (begin
             (display "Hello, ")
             (display whom)
             (display " !\n") ) ) ) )

      (define (hello)
        (greet "world") )  )

The module `test` exports one value (`hello`) and one syntax binding (`greet`). To use it in `csi`, the interpreter, simply load and import it:

     #;1> ,l hello.scm
     ; loading hello.scm ...
     ; loading /usr/local/lib/chicken/4/scheme.import.so ...
     #;1> (import test)
     #;2> (hello)
     Hello, world !
     #;3> (greet "you")
     Hello, you !

The module can easily be compiled

     % csc -s hello.scm

and used in an identical manner:

     #;1> ,l hello.so
     ; loading hello.so ...
     #;1> (import test)
     #;2> (hello)
     Hello, world !
     #;3> (greet "you")
     Hello, you !

If you want to keep macro-definitions in a separate file, use import libraries:

     % csc -s hello.scm -j test
     % csc -s test.import.scm

     #;1> ,l hello.so
     ; loading hello.so ...
     #;1> (import test)
     ; loading ./test.import.so ...
     #;2> (hello)
     Hello, world !
     #;3> (greet "you")
     Hello, you !

If an import library (compiled or in source-form) is located somewhere in the extensions-repository or include path, it is automatically loaded on import. Otherwise you have to load it manually:

     #;1> ,l hello.so
     ; loading hello.so ...
     #;1> ,l test.import.so
     ; loading test.import.so ...
     #;1> (import test)
     #;2>

Note that you must us import libraries if you compile code that depends on other modules. The compiler will not execute the modules that are refered to by compiled code, and thus the binding information and exported syntax of the former must be available separately.

### Caveats

The macro- and module system has been implemented relatively recently and is likely to contain bugs. Please contact the maintainers if you encounter behavior that you think is not correct or that triggers an error where there shouldn't be one.

- In evaluated code, loading a file containing module information and importing from a module contained in that file will not work when the loading and import is performed in the same toplevel expression (this does not apply, when import libraries are used)
- Currently value bindings imported by `import` and `import-for-syntax` share the same import-environment.

Previous: Macros

Next: Declarations