Modules

Definitions

Modules provide a way to encapsulate programs. A module is a logical unit containing a set of procedures, variables, etc as a separate entity. Module is represented by its name which is a symbol. It also can be called a library.

Requirements

Module system does:

1. Load libraries.
2. Resolve dependencies.
3. Load platform optimized library code.
4. Dump Shen programs with support of platform-specific libraries code.
5. Is implemented as external to Shen library.

Implementation

See modulesys.shen in shen-libs.

Defining module

A module consists of manifest file and source files. A manifest file is an ordinary Shen source which contains single definition register-module.

Module's manifest

(register-module
 [ [author: "Mr. R"]
   [license: "Public domain"]
   [version: "1.2"]
   [desc: "Module for performing YYY"]
   [depends: Module-B Module-C]
   [load: "module-a-src.shen"
          "module-a-src2.shen"]
   [translate: "module-a-src.shen"
               "module-a-src2.shen"] ] )

Where name is required.

author: (string) an author of a module. Not used by module system itself.

license: (string) a license of a module. Not used by module system itself.

version: (string) a version of a module. Not used by module system itself.

desc: (string) a short description of a module. Not used by module system itself.

depends: (list module-id) dependencies of a module.

load: (list string) a list of module source files to load. A files' path is relative to a directory with manifest.

translate: (list string) a list of module source files to translate when translatin a module to a target platform. If not defined then modulesys uses files defined in load directive.

load-fn: (symbol) a name of function modulesys calls when loading a module instead of using a list defined in load directive. If load-fn is defined then load field is ignored. A function should be defined in this manifest file and has a type of (--> boolean).

unload-fn: (symbol) a name of function what is called before module is reloaded. It can remove specific macros and so on.

translate-fn: (symbol) a name of function that returns a list of sources to translate. The result of this function is used instead of list defined in translate directive. A function should be defined in this manifest file. If translate-fn is defined then translate field is ignored.

Functions in load-fn and unload-fn have the type: --> boolean.

Function in translate-fn takes target language, target implementation as arguments and has the type: string --> string --> (list string). That function is invoked with *home-directory* set to directory where current module manifest is located.

Module filesystem

A module Module is stored in a directory Module. That directory is searched in directories defined in modules.*paths* list. A module's manifest is named module.shen.

Mod-X/
  module.shen
  mod-x.shen
  cl.lisp
  cl-sbcl.lisp
  ...
  scheme.scm
  scheme/
    gambit.scm
    chibi.scm

Using modules

Defining modules locations

Modules are searched in a list of paths stored in a global variable *modules-paths*. Each entry which is not equal to "" must end with /.

Loading module

(module.use Modules)

type: (list module-id) --> boolean

module.use loads given modules with all their dependencies. Any module already loaded won't be loaded twice. Use reload-module to reload modules.

Dumping system

(module.files-to-translate Module Lang Impl)

type: module-id --> string --> string --> (list string)

Returns a list of source files to translate module Module with all its dependencies to target platform defined by Lang and Impl parameters.

Reloading module

Sometimes it is required to reload a new version of module but use-module doesn't reload modules.

(module.reload Module)

type: module-id --> boolean

Reloads a module Module.

Platform-dependent modules

Module may optionally contain platform-dependent files. Platform-dependent files are used instead of common module code on corresponding platforms. It allows to have platform-optimized version of module functions.