6.19.1 General Information about Modules

A Guile module can be thought of as a collection of named procedures, variables and macros. More precisely, it is a set of bindings of symbols (names) to Scheme objects.

An environment is a mapping from identifiers (or symbols) to locations, i.e., a set of bindings. There are top-level environments and lexical environments. The environment in which a lambda is executed is remembered as part of its definition.

Within a module, all bindings are visible. Certain bindings can be declared public, in which case they are added to the module’s so-called export list; this set of public bindings is called the module’s public interface (see section Creating Guile Modules).

A client module uses a providing module’s bindings by either accessing the providing module’s public interface, or by building a custom interface (and then accessing that). In a custom interface, the client module can select which bindings to access and can also algorithmically rename bindings. In contrast, when using the providing module’s public interface, the entire export list is available without renaming (see section Using Guile Modules).

To use a module, it must be found and loaded. All Guile modules have a unique module name, which is a list of one or more symbols. Examples are (ice-9 popen) or (srfi srfi-11). When Guile searches for the code of a module, it constructs the name of the file to load by concatenating the name elements with slashes between the elements and appending a number of file name extensions from the list %load-extensions (see section Loading Scheme Code from File). The resulting file name is then searched in all directories in the variable %load-path (see section Configuration, Build and Installation). For example, the (ice-9 popen) module would result in the filename ice-9/popen.scm and searched in the installation directories of Guile and in all other directories in the load path.

A slightly different search mechanism is used when a client module specifies a version reference as part of a request to load a module (see section R6RS Version References). Instead of searching the directories in the load path for a single filename, Guile uses the elements of the version reference to locate matching, numbered subdirectories of a constructed base path. For example, a request for the (rnrs base) module with version reference (6) would cause Guile to discover the rnrs/6 subdirectory (if it exists in any of the directories in the load path) and search its contents for the filename base.scm.

When multiple modules are found that match a version reference, Guile sorts these modules by version number, followed by the length of their version specifications, in order to choose a “best” match.

Every module has a so-called syntax transformer associated with it. This is a procedure which performs all syntax transformation for the time the module is read in and evaluated. When working with modules, you can manipulate the current syntax transformer using the use-syntax syntactic form or the #:use-syntax module definition option (see section Creating Guile Modules).