5.16.3.2 Using Guile Modules

To use a Guile module is to access either its public interface or a custom interface (see General Information about Modules). Both types of access are handled by the syntactic form use-modules, which accepts one or more interface specifications and, upon evaluation, arranges for those interfaces to be available to the current module. This process may include locating and loading code for a given module if that code has not yet been loaded, following %load-path (see Build Config).

An interface specification has one of two forms. The first variation is simply to name the module, in which case its public interface is the one accessed. For example:

     (use-modules (ice-9 popen))

Here, the interface specification is (ice-9 popen), and the result is that the current module now has access to open-pipe, close-pipe, open-input-pipe, and so on (see Included Guile Modules).

Note in the previous example that if the current module had already defined open-pipe, that definition would be overwritten by the definition in (ice-9 popen). For this reason (and others), there is a second variation of interface specification that not only names a module to be accessed, but also selects bindings from it and renames them to suit the current module's needs. For example:

     (use-modules ((ice-9 popen)
                   :select ((open-pipe . pipe-open) close-pipe)
                   :renamer (symbol-prefix-proc 'unixy:)))

Here, the interface specification is more complex than before, and the result is that a custom interface with only two bindings is created and subsequently accessed by the current module. The mapping of old to new names is as follows:

     (ice-9 popen) sees:             current module sees:
     open-pipe                       unixy:pipe-open
     close-pipe                      unixy:close-pipe

This example also shows how to use the convenience procedure symbol-prefix-proc.

You can also directly refer to bindings in a module by using the @ syntax. For example, instead of using the use-modules statement from above and writing unixy:pipe-open to refer to the pipe-open from the (ice-9 popen), you could also write (@ (ice-9 popen) open-pipe). Thus an alternative to the complete use-modules statement would be

     (define unixy:pipe-open (@ (ice-9 popen) open-pipe))
     (define unixy:close-pipe (@ (ice-9 popen) close-pipe))

There is also @@, which can be used like @, but does not check whether the variable that is being accessed is actually exported. Thus, @@ can be thought of as the impolite version of @ and should only be used as a last resort or for debugging, for example.

Note that just as with a use-modules statement, any module that has not yet been loaded yet will be loaded when referenced by a @ or @@ form.

You can also use the @ and @@ syntaxes as the target of a set! when the binding refers to a variable.