— syntax: define-module module-name [options ...]

module-name is of the form (hierarchy file). One example of this is

          (define-module (ice-9 popen))
     

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

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

#:use-module interface-specification

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

#:use-syntax module

Use module when loading the currently defined module, and install it as the syntax transformer.

#: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. 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. The symbols in list must be imported by the current module from other modules. This is equivalent to re-export below.

#:export-syntax list

Export all identifiers in list which must be a list of symbols. The identifiers in list must refer to macros (see Macros) defined in the current module. This is equivalent to (export-syntax list) in the module body.

#:re-export-syntax list

Re-export all identifiers in list which must be a list of symbols. The symbols in list must refer to macros imported by the current module from other modules. This is equivalent to (re-export-syntax list) in the module body.

#:replace list

Export all identifiers in list (a list 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.

This is useful for modules that export bindings that have the same name as core bindings. #: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.

For instance, SRFI-39 exports a binding named current-input-port (see SRFI-39) that is a function which is upwardly compatible with the core current-input-port function. Therefore, SRFI-39 exports its version with #:replace.

SRFI-19, on the other hand, exports its own version of current-time (see SRFI-19 Time) which is not compatible with the core current-time function (see Time). Therefore, SRFI-19 does not use #:replace.

The #:replace option can also be used by a module which is intentionally producing a new special kind of environment and should override any core or other bindings already in scope. For example perhaps a logic processing environment where <= is an inference instead of a comparison.

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

#: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:

1. 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.
2. 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.
3. 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.

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

               (replace warn-override-core warn last)
          

#:no-backtrace

Tell Guile not to record information for procedure backtraces when executing the procedures in this module.

#: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) to the list of exported bindings of the current module.

— syntax: define-public ...

Equivalent to (begin (define foo ...) (export foo)).

— syntax: re-export variable ...

Add all variables (which must be symbols) to the list of re-exported bindings of the current module. Re-exported bindings must be imported by the current module from some other module.