Guile Reference Manual: Creating Guile Modules

Warning: This is the manual of the legacy Guile 2.0 series. You may want to read the manual of the current stable series instead.

6.19.3 Creating Guile Modules

When you want to create your own modules, you have to take the following steps:

Create a Scheme source file and add all variables and procedures you wish to export, or which are required by the exported procedures.
Add a define-module form at the beginning.
Export all bindings which should be in the public interface, either by using define-public or export (both documented below).

syntax: define-module module-name option …

module-name is a list of one or more symbols.

(define-module (ice-9 popen))

define-module makes this module available to Guile programs under the given module-name.

option … are keyword/value pairs which specify more about the defined module. The recognized options and their meaning are shown in the following table.

#:use-module interface-specification

Equivalent to a (use-modules interface-specification) (see Using Guile Modules).

#:autoload module symbol-list

Load module when any of symbol-list are accessed. For example,

(define-module (my mod)
  #:autoload (srfi srfi-1) (partition delete-duplicates))
...
(if something
    (set! foo (delete-duplicates ...)))

When a module is autoloaded, all its bindings become available. symbol-list is just those that will first trigger the load.

An autoload is a good way to put off loading a big module until it’s really needed, for instance for faster startup or if it will only be needed in certain circumstances.

@ can do a similar thing (see Using Guile Modules), but in that case an @ form must be written every time a binding from the module is used.

#:export list

Export all identifiers in list which must be a list of symbols or pairs of symbols. This is equivalent to (export list) in the module body.

#:re-export list

Re-export all identifiers in list which must be a list of symbols or pairs of symbols. The symbols in list must be imported by the current module from other modules. This is equivalent to re-export below.

#:replace list

Export all identifiers in list (a list of symbols or pairs of symbols) and mark them as replacing bindings. In the module user’s name space, this will have the effect of replacing any binding with the same name that is not also “replacing”. Normally a replacement results in an “override” warning message, #:replace avoids that.

In general, a module that exports a binding for which the (guile) module already has a definition should use #:replace instead of #:export. #:replace, in a sense, lets Guile know that the module purposefully replaces a core binding. It is important to note, however, that this binding replacement is confined to the name space of the module user. In other words, the value of the core binding in question remains unchanged for other modules.

Note that although it is often a good idea for the replaced binding to remain compatible with a binding in (guile), to avoid surprising the user, sometimes the bindings will be incompatible. For example, SRFI-19 exports its own version of current-time (see SRFI-19 Time) which is not compatible with the core current-time function (see Time). Guile assumes that a user importing a module knows what she is doing, and uses #:replace for this binding rather than #:export.

A #:replace clause is equivalent to (export! list) in the module body.

The #:duplicates (see below) provides fine-grain control about duplicate binding handling on the module-user side.

#:version list

Specify a version for the module in the form of list, a list of zero or more exact, nonnegative integers. The corresponding #:version option in the use-modules form allows callers to restrict the value of this option in various ways.

#:duplicates list

Tell Guile to handle duplicate bindings for the bindings imported by the current module according to the policy defined by list, a list of symbols. list must contain symbols representing a duplicate binding handling policy chosen among the following:

check

Raises an error when a binding is imported from more than one place.

warn

Issue a warning when a binding is imported from more than one place and leave the responsibility of actually handling the duplication to the next duplicate binding handler.

replace

When a new binding is imported that has the same name as a previously imported binding, then do the following:

If the old binding was said to be replacing (via the #:replace option above) and the new binding is not replacing, the keep the old binding.
If the old binding was not said to be replacing and the new binding is replacing, then replace the old binding with the new one.
If neither the old nor the new binding is replacing, then keep the old one.

warn-override-core

Issue a warning when a core binding is being overwritten and actually override the core binding with the new one.

first

In case of duplicate bindings, the firstly imported binding is always the one which is kept.

last

In case of duplicate bindings, the lastly imported binding is always the one which is kept.

noop

In case of duplicate bindings, leave the responsibility to the next duplicate handler.

If list contains more than one symbol, then the duplicate binding handlers which appear first will be used first when resolving a duplicate binding situation. As mentioned above, some resolution policies may explicitly leave the responsibility of handling the duplication to the next handler in list.

If GOOPS has been loaded before the #:duplicates clause is processed, there are additional strategies available for dealing with generic functions. See Merging Generics, for more information.

The default duplicate binding resolution policy is given by the default-duplicate-binding-handler procedure, and is

(replace warn-override-core warn last)

#:pure

Create a pure module, that is a module which does not contain any of the standard procedure bindings except for the syntax forms. This is useful if you want to create safe modules, that is modules which do not know anything about dangerous procedures.

syntax: export variable …: Add all variables (which must be symbols or pairs of symbols) to the list of exported bindings of the current module. If variable is a pair, its car gives the name of the variable as seen by the current module and its cdr specifies a name for the binding in the current module’s public interface.

syntax: define-public …: Equivalent to (begin (define foo ...) (export foo)).

syntax: re-export variable …: Add all variables (which must be symbols or pairs of symbols) to the list of re-exported bindings of the current module. Pairs of symbols are handled as in export. Re-exported bindings must be imported by the current module from some other module.

syntax: export! variable …: Like export, but marking the exported variables as replacing. Using a module with replacing bindings will cause any existing bindings to be replaced without issuing any warnings. See the discussion of #:replace above.