Warning: This is the manual of the legacy Guile 2.2 series. You may want to read the manual of the current stable series instead.
Next: Modules and the File System, Previous: Using Guile Modules, Up: Modules [Contents][Index]
When you want to create your own modules, you have to take the following steps:
define-module
form at the beginning.
define-public
or export
(both documented below).
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:
#:replace
option above) and the new binding is not replacing,
the keep the old binding.
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.
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.
Equivalent to (begin (define foo ...) (export foo))
.
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.
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.
Next: Modules and the File System, Previous: Using Guile Modules, Up: Modules [Contents][Index]