Modutils - Module utility for STk

version 0.0

1. Overview

STk has a couple of mechanisms to support developing libraries in a modular way: traditional Lisp's feature based loading functions (`require' and `provide'), and a simple module system to separate namespaces.

Although those two functionalities are independent, they are quite useful if combined; i.e. you implement a particular library in one namespace (module), and allow the user of the library to load necessary file(s) via the require function. Unfortunately, the user of the library has to write both require and import in order to do that, which would become crumsy if he/she wants to use lots of libraries.

Also, the libraries may be updated independently, for fixing bugs or adding new features. Some libraries depend on the other, and requires particular version of the library to be installed. In the production environment, this kind of dependency tracking and version control are mandatory.

This module provides an ad-hoc support for these issues on top of existing STk built-in functionalities. So far, it supports the following

Integrated load and import: You can `require' a certain library and import its interface simultaneously.
Selective import: Besides the symbols exported by the module by default, you can import addtional symbols in convenient way.
Version checking: You can declare that your code requires a certain version or newer of the library.

2. Installation

The newest version of the library is 0.0 at the time I'm writing this. It can be obtained from http://practical-scheme.net/vault/modutils-0.0.tar.gz.

If you read this document off-line, check out the newest document online. http://practical-scheme.net/vault/modutils.html.

Once you get the package, you can install it by the following procedure.

Ungzip+untar the package
cd modutils
stk Makefile.stk
make install

3. Working with modules

You can implement a certain module in a single file, or a group of files. However, it'll be convenient to have one single "main" file, which loads other files (or, you can set up to autoload necessary files on demand).

The main file needs to define a module and its interface. When you use modutils, the skeleton of the file will look like this:

    ;; file mymodule.stk
    (define-module mymodule
      (require "modutils")       ; modutils itself inserts necessary symbols
                                 ; to the global namespace, so you don't
                                 ; need to import them explicitly.

      (module-version "1.7.13")  ; Set the version of this module.

      (export extfn1 extfn2)     ; Declare external symbols, 
                                 ;  using STk's export macro.

      (export-ok optfn1 optfn2)  ; Symbols which may be used by the user library
                                 ;  if requested.

      ;; module body comes here.

    )
    (provide "mymodule")

The file name doesn't need to match the module name ("mymodule"), but generally it is move convenient to keep them the same.

The user of the module can be like this:

    (require "modutils")         ; to use modutils functionality

    (use-module mymodule         ; load mymodule and import the external symbols.
      :minimum-version "1.6")    ;   requiring version 1.6 or later.

    (use-module yourmodule       ; load another module.  In this case the file
      :file "yourlib/YourModule" ;    name can't be inferred from module name.
      :extra-import (aaa bbb))   ; Besides the external symbols, import optional
                                 ;    symbols.

    (use-module stdlibs)         ; the simplest form

    ;; body of your code

4. Writing modules

Macro: module-version VERSIONSTR

Declares the version of this module. VERSIONSTR is a string which matches the following regexp:

   [0-9]+(\.[0-9]+)*

The behavior of module-version is undefined if called other than toplevel environment (the body of define-module is ok).

Macro: export-ok SYMBOL ...: Allows SYMBOLs to be imported by the user library when explicitly requested.
The behavior of export-ok is undefined if called other than toplevel environment (the body of define-module is ok).

5. Using modules

Macro: use-module NAME &key file minimum-version extra-import

Load the named module and import its external symbols to the current package.

If the file keyword argument is given, its value is passed to require to load the file. Otherwise, (symbol->string NAME) is used as the file name. Note that the load function puts an appropriate suffix to the file name.

When minimum-version is given, that must be a string obeying a regular expression [0-9]+(\.[0-9]+)*. The given version and the module's provided version is compared, and if the module's are lower than the minimum-version, an error is signalled. If no version is provided in the module, it is lower than any explicit version.

The version is compared as this: each version string is splitted by dots into a list of integers. The first element of each version is compared numerically, and if two of them are the same, the next elements are tried. If one of the version runs out an element, that version is lower than the other, e.g.:

   1 < 1.1
   1.1 < 1.10
   1.99 < 2.0
   2.3.1.1 < 2.3.1.2

The argument for keyword extra-import must be a list of symbols, and each symbols are imported from the module NAME to the current module. The symbol must be listed in the export-ok list of the module NAME.

The behavior of use-module is undefined if called other than toplevel environment.

Macro: use-lib PATH ...: A convenient macro to add PATHs to *load-path*. PATHs are added in front of current *load-path*.

6. Ideas

When a minimum-version requirement failed, it is desirable to search the *load-path* further to find the one satisfies the requirement. In the production environment, it is very useful since you cannot just update one of the library until you make sure all the existing tools works with the new version (such test is not easy to conduct in the large production), while the new application you want to use requires the new version of the library.
export-from macro for cascading export (export the external symbols of parent module).

Index

Jump to: e - m - u

This document was generated on 17 October 2000 using texi2html 1.56k.

Modutils - Module utility for STk

version 0.0

Table of Contents