6.20.8 Module System Reflection

The previous sections have described a declarative view of the module system. You can also work with it programmatically by accessing and modifying various parts of the Scheme objects that Guile uses to implement the module system.

At any time, there is a current module. This module is the one where a top-level define and similar syntax will add new bindings. You can find other module objects with resolve-module, for example.

These module objects can be used as the second argument to eval.

Scheme Procedure: current-module

C Function: scm_current_module ()

Return the current module object.

Scheme Procedure: set-current-module module

C Function: scm_set_current_module (module)

Set the current module to module and return the previous current module.

Scheme Procedure: save-module-excursion thunk

Call thunk within a dynamic-wind such that the module that is current at invocation time is restored when thunk’s dynamic extent is left (see Dynamic Wind).

More precisely, if thunk escapes non-locally, the current module (at the time of escape) is saved, and the original current module (at the time thunk’s dynamic extent was last entered) is restored. If thunk’s dynamic extent is re-entered, then the current module is saved, and the previously saved inner module is set current again.

Scheme Procedure: resolve-module name [autoload=#t] [version=#f] [#:ensure=#t]

C Function: scm_resolve_module (name)

Find the module named name and return it. When it has not already been defined and autoload is true, try to auto-load it. When it can’t be found that way either, create an empty module if ensure is true, otherwise return #f. If version is true, ensure that the resulting module is compatible with the given version reference (see R6RS Version References). The name is a list of symbols.

Scheme Procedure: resolve-interface name [#:select=#f] [#:hide='()] [#:prefix=#f] [#:renamer=#f] [#:version=#f]

Find the module named name as with resolve-module and return its interface. The interface of a module is also a module object, but it contains only the exported bindings.

Scheme Procedure: module-uses module

Return a list of the interfaces used by module.

Scheme Procedure: module-use! module interface

Add interface to the front of the use-list of module. Both arguments should be module objects, and interface should very likely be a module returned by resolve-interface.

Scheme Procedure: reload-module module

Revisit the source file that corresponds to module. Raises an error if no source file is associated with the given module.

As mentioned in the previous section, modules contain a mapping between identifiers (as symbols) and storage locations (as variables). Guile defines a number of procedures to allow access to this mapping. If you are programming in C, Accessing Modules from C.

Scheme Procedure: module-variable module name

Return the variable bound to name (a symbol) in module, or #f if name is unbound.

Scheme Procedure: module-add! module name var

Define a new binding between name (a symbol) and var (a variable) in module.

Scheme Procedure: module-ref module name

Look up the value bound to name in module. Like module-variable, but also does a variable-ref on the resulting variable, raising an error if name is unbound.

Scheme Procedure: module-define! module name value

Locally bind name to value in module. If name was already locally bound in module, i.e., defined locally and not by an imported module, the value stored in the existing variable will be updated. Otherwise, a new variable will be added to the module, via module-add!.

Scheme Procedure: module-set! module name value

Update the binding of name in module to value, raising an error if name is not already bound in module.

There are many other reflective procedures available in the default environment. If you find yourself using one of them, please contact the Guile developers so that we can commit to stability for that interface.