5.12.1 Informal Module Introduction

This is a quick but informal introduction on Rep module system.

What’s a module? First, a module is identified by its name. Each has its local bindings, i.e. variables and functions. (Remember that functions can be stored in variables.) Local bindings can be referred to inside of the module. And a module can specify which bindings are “exported”, that is, visible to outer worlds.

Ok, so let’s use an existing module. How can it be done? To load a module dynamically, use require:

(require 'rep.util.time) ;; Module name is a symbol

Looks like Elips, but forget it; Elisp doesn’t have the module system. There’s no provide in modules.

In fact, two things are done by require. First, the module is loaded into the Rep if it’s not yet, and second, the bindings declared to be “exported” are imported to the current module.

Current module? Yes, the current module always exists. If you’re using the REPL, then it’s user module. Also the module which the REPL of sawfish-client and Sawfish’s ~/.sawfish/rc dwell is called user.

When you want to use, say rep.util.time from another module, then you have to call require again from there.

In this manual, the module in which a function is defined is explicitly shown. If any module isn’t named, then you don’t have to require any. (In fact, rep module is necessary, but you can forget it now.)

If you look at /usr/share/rep/x.y.z/lisp/rep/util/time.jl, then it exports for example seconds->time. Now you can call it.

(seconds->time (* 3600 72))
  ⇒ (3 . 0) ;; Cons of days and the rest in seconds.

The file time.jl is a good example, because it’s small. Please have a look at it. You now know how to define a module. In the open clause, you declare which modules you import to that module. require is a usual function, but open is only used in the definition of a module. time module opens only one module, rep.

In a module definition, first comes define-structure (“structure” is a synonym for “module”), then export, and open. After them come usual expressions, and they’re evaluated in that module. You can put there anything, not limited to defines.

Module name and file name

How does a module name corresponds to a file name? When loading, modules are searched from load-path. If you’re using Sawfish in a Unix, its first element is ~/.sawfish/lisp, the second /usr/share/sawfish/<version>/lisp, and so on.

Now assume load-path is (a b). When you require the module foo.bar, then a/foo/bar.jl is tried e.g. in Unix, since the directory separator is a slash ’/’, and if it exists, it’s loaded. If not, b/foo/bar.jl is tried. If it fails, an error is signaled.

A good news. If there’re both a byte compiled file and a plain lisp source, and if the compiled one is older, then the source is loaded. In short, always the newer one is used.