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
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
(see Modules and the File System).
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-input-pipe, and so on (see Pipes).
Note in the previous example that if the current module had already
open-pipe, that definition would be overwritten by the
(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:)))
or more simply:
(use-modules ((ice-9 popen) #:select ((open-pipe . pipe-open) close-pipe) #:prefix 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
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
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
@@ can be thought of as the impolite version
@ 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 will be loaded when referenced by a
You can also use the
@@ syntaxes as the target
set! when the binding refers to a variable.
Return a procedure that prefixes its arg (a symbol) with prefix-sym.
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 [#:select SELECTION] [#:prefix PREFIX] [#:renamer RENAMER])
in which case a custom interface is newly created and used.
module-name is a list of symbols, as above; selection is a
list of selection-specs; prefix is a symbol that is prepended to
imported names; and renamer is a procedure that takes a symbol and
returns its new name. A selection-spec is either a symbol or a pair of
(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 modified by prefix and renamer.
#:renamer clauses are
optional. If all are omitted, the returned interface has no bindings.
#:select clause is omitted, prefix and renamer
operate on the used module’s public interface.
In addition to the above, spec can also include a
clause, of the form:
where version-spec is an R6RS-compatible version reference. An error will be signaled in the case in which a module with the same name has already been loaded, if that module specifies a version and that version is not compatible with version-spec. See R6RS Version References, for more on version references.
If the module name is not resolvable,
use-modules will signal an
Refer to the binding named binding-name in module module-name. The binding must have been exported by the module.
Refer to the binding named binding-name in module module-name. The binding must not have been exported by the module. This syntax is only intended for debugging purposes or as a last resort.