Next: Creating Guile Modules, Previous: Loading Guile Modules, Up: Modules
To use a Guile module is to access either its public interface or a
custom interface (see Module System Basics). 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 (see Install 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 module in which this module is evaluated gains
access to open-pipe, close-pipe, open-input-pipe,
and so on.
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.
Return a procedure that prefixes its arg (a symbol) with prefix (also a symbol). Optional arg cut specifies the number of characters to remove from the head of the original symbol before prefixing (useful for substitution).
Resolve each interface specification spec into an interface and arrange for these to be accessible by the current module. The return value is unspecified.
spec can be a list of symbols, in which case it names a module whose public interface is found and used.
spec can also be of the form:
(MODULE-NAME [KEYWORD VALUE ...])in which case a custom interface for module-name (a list of symbols, as above) is newly created and used, as specified by the keywords and their values. Supported keywords:
#:select (selection-spec ...)- Each selection-spec is either a symbol naming the variable directly, or a pair of symbols
(ORIG . SEEN), where orig is the name in the used module and seen is the name in the using module. Note that seen is also passed through renamer, described immediately below.#:renamer renamer- renamer is a procedure that takes a symbol and returns another one — its new name.
#:prefix symbol- This is a common case of renaming whereby each name is prefixed with symbol. If both
#:renamerand#:prefixare specified,#:renamertakes precedence.Both steps in specifying a custom interface, selection and renaming, are optional. If both are omitted, the returned interface has no bindings. If selection is omitted, renaming operates on the used module's public interface.
Signal error if module name is not resolvable.