3.7 Writing Gauche modules

Gauche’s libraries are organized by modules. Although Gauche can load any valid Scheme programs, there is a convention that Gauche’s libraries follow. When you write a chunk of Scheme code for Gauche, it is convenient to make it a module, so that it can be shared and/or reused.

Usually a module is contained in a file, but you can make a multi-file module. First I explain the structure of a single-file module. The following template is the convention used in Gauche’s libraries.

;; Define the module interface
(define-module foo
  (use xxx)
  (use yyy)
  (export foo1 foo2 foo3)
  )
;; Enter the module
(select-module foo)

… module body …

This file must be saved as “foo.scm” in some directory in the *load-path*.

The define-module form creates a module foo. It also loads and imports some other modules by ‘use’ macros, and declares which symbols the foo module exports, by ‘export’ syntax. (See section Defining and selecting modules, for detailed specification of those syntaxes).

Those use forms or export forms are not required to appear in the define-module form, but it is a good convention to keep them in there at the head of the file so that it is visually recognizable which modules foo depends and which symbols it exports.

The second form, ‘select-module’, specifies the rest of the file is evaluated in the module foo you just defined. Again, this is just a convention; you can write entire module body inside define-module. However, I think it is error-prone, for the closing parenthesis can be easily forgotten or the automatic indentation mechanism of editor will be confused.

After select-module you can write whatever Scheme expression. It is evaluated in the selected module, foo. Only the bindings of the exported symbols will be directly accessible from outside.

So, that’s it. Other programs can use your module by just saying ‘(use foo)’. If you want to make your module available on your site, you can put it to the site library location, which can be obtained by

(gauche-site-library-directory)

in gosh, or

gauche-config --sitelibdir

from shell.

If you feel like to conserve global module name space, you can organize modules hierarchically. Some Gauche libraries already does so. See Library modules - Overview, for examples. For example, text.tr module is implemented in “text/tr.scm” file. Note that the pathname separator ‘/’ in the file becomes a period in the module name.