@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000-2004, 2007-2014
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
-@page
@node Modules
@section Modules
@cindex modules
In addition, Guile offers variables as first-class objects. They can
be used for interacting with the module system.
-@menu
-* provide and require:: The SLIB feature mechanism.
-* Environments:: R5RS top-level environments.
-* The Guile module system:: How Guile does it.
-* Dynamic Libraries:: Loading libraries of compiled code at run time.
-* Variables:: First-class variables.
-@end menu
-
-@node provide and require
-@subsection provide and require
-
-Aubrey Jaffer, mostly to support his portable Scheme library SLIB,
-implemented a provide/require mechanism for many Scheme implementations.
-Library files in SLIB @emph{provide} a feature, and when user programs
-@emph{require} that feature, the library file is loaded in.
-
-For example, the file @file{random.scm} in the SLIB package contains the
-line
-
-@smalllisp
-(provide 'random)
-@end smalllisp
-
-so to use its procedures, a user would type
-
-@smalllisp
-(require 'random)
-@end smalllisp
-
-and they would magically become available, @emph{but still have the same
-names!} So this method is nice, but not as good as a full-featured
-module system.
-
-When SLIB is used with Guile, provide and require can be used to access
-its facilities.
-
-@node Environments
-@subsection Environments
-@cindex environment
-
-Scheme, as defined in R5RS, does @emph{not} have a full module system.
-However it does define the concept of a top-level @dfn{environment}.
-Such an environment maps identifiers (symbols) to Scheme objects such
-as procedures and lists: @ref{About Closure}. In other words, it
-implements a set of @dfn{bindings}.
-
-Environments in R5RS can be passed as the second argument to
-@code{eval} (@pxref{Fly Evaluation}). Three procedures are defined to
-return environments: @code{scheme-report-environment},
-@code{null-environment} and @code{interaction-environment} (@pxref{Fly
-Evaluation}).
-
-In addition, in Guile any module can be used as an R5RS environment,
-i.e., passed as the second argument to @code{eval}.
-
-Note: the following two procedures are available only when the
-@code{(ice-9 r5rs)} module is loaded:
-
-@smalllisp
-(use-modules (ice-9 r5rs))
-@end smalllisp
-
-@deffn {Scheme Procedure} scheme-report-environment version
-@deffnx {Scheme Procedure} null-environment version
-@var{version} must be the exact integer `5', corresponding to revision
-5 of the Scheme report (the Revised^5 Report on Scheme).
-@code{scheme-report-environment} returns a specifier for an
-environment that is empty except for all bindings defined in the
-report that are either required or both optional and supported by the
-implementation. @code{null-environment} returns a specifier for an
-environment that is empty except for the (syntactic) bindings for all
-syntactic keywords defined in the report that are either required or
-both optional and supported by the implementation.
-
-Currently Guile does not support values of @var{version} for other
-revisions of the report.
-
-The effect of assigning (through the use of @code{eval}) a variable
-bound in a @code{scheme-report-environment} (for example @code{car})
-is unspecified. Currently the environments specified by
-@code{scheme-report-environment} are not immutable in Guile.
-@end deffn
-
-@node The Guile module system
-@subsection The Guile module system
-
-The Guile module system extends the concept of environments, discussed
-in the previous section, with mechanisms to define, use and customise
-sets of bindings.
-
-In 1996 Tom Lord implemented a full-featured module system for Guile which
-allows loading Scheme source files into a private name space. This system has
-been in available since at least Guile version 1.1.
-
-For Guile version 1.5.0 and later, the system has been improved to have better
-integration from C code, more fine-grained user control over interfaces, and
-documentation.
-
-Although it is anticipated that the module system implementation will
-change in the future, the Scheme programming interface described in this
-manual should be considered stable. The C programming interface is
-considered relatively stable, although at the time of this writing,
-there is still some flux.
-
@menu
* General Information about Modules:: Guile module basics.
* Using Guile Modules:: How to use existing modules.
* Creating Guile Modules:: How to package your code into modules.
-* Module System Reflection:: Accessing module objects at run-time.
-* Module System Quirks:: Strange things to be aware of.
-* Included Guile Modules:: Which modules come with Guile?
+* Modules and the File System:: Installing modules in the file system.
+* R6RS Version References:: Using version numbers with modules.
+* R6RS Libraries:: The library and import forms.
+* Variables:: First-class variables.
+* Module System Reflection:: First-class modules.
* Accessing Modules from C:: How to work with modules with C code.
+* provide and require:: The SLIB feature mechanism.
+* Environments:: R5RS top-level environments.
@end menu
@node General Information about Modules
-@subsubsection General Information about Modules
+@subsection General Information about Modules
A Guile module can be thought of as a collection of named procedures,
variables and macros. More precisely, it is a set of @dfn{bindings}
of symbols (names) to Scheme objects.
-An environment is a mapping from identifiers (or symbols) to locations,
-i.e., a set of bindings.
-There are top-level environments and lexical environments.
-The environment in which a lambda is executed is remembered as part of its
-definition.
-
Within a module, all bindings are visible. Certain bindings
can be declared @dfn{public}, in which case they are added to the
module's so-called @dfn{export list}; this set of public bindings is
providing module's public interface, the entire export list is available
without renaming (@pxref{Using Guile Modules}).
-To use a module, it must be found and loaded. All Guile modules have a
-unique @dfn{module name}, which is a list of one or more symbols.
-Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}. When Guile
-searches for the code of a module, it constructs the name of the file to
-load by concatenating the name elements with slashes between the
-elements and appending a number of file name extensions from the list
-@code{%load-extensions} (@pxref{Loading}). The resulting file name is
-then searched in all directories in the variable @code{%load-path}
-(@pxref{Build Config}). For example, the @code{(ice-9 popen)} module
-would result in the filename @code{ice-9/popen.scm} and searched in the
-installation directories of Guile and in all other directories in the
-load path.
-
-@c FIXME::martin: Not sure about this, maybe someone knows better?
-Every module has a so-called syntax transformer associated with it.
-This is a procedure which performs all syntax transformation for the
-time the module is read in and evaluated. When working with modules,
-you can manipulate the current syntax transformer using the
-@code{use-syntax} syntactic form or the @code{#:use-syntax} module
-definition option (@pxref{Creating Guile Modules}).
-
-Please note that there are some problems with the current module system
-you should keep in mind (@pxref{Module System Quirks}). We hope to
-address these eventually.
+All Guile modules have a unique @dfn{module name}, for example
+@code{(ice-9 popen)} or @code{(srfi srfi-11)}. Module names are lists
+of one or more symbols.
+
+When Guile goes to use an interface from a module, for example
+@code{(ice-9 popen)}, Guile first looks to see if it has loaded
+@code{(ice-9 popen)} for any reason. If the module has not been loaded
+yet, Guile searches a @dfn{load path} for a file that might define it,
+and loads that file.
+The following subsections go into more detail on using, creating,
+installing, and otherwise manipulating modules and the module system.
@node Using Guile Modules
-@subsubsection Using Guile Modules
+@subsection Using Guile Modules
To use a Guile module is to access either its public interface or a
custom interface (@pxref{General Information about Modules}). Both
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 %load-path (@pxref{Build
-Config}).
+that code has not yet been loaded, following @code{%load-path}
+(@pxref{Modules and the File System}).
An @dfn{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:
-@smalllisp
+@lisp
(use-modules (ice-9 popen))
-@end smalllisp
+@end lisp
Here, the interface specification is @code{(ice-9 popen)}, and the
result is that the current module now has access to @code{open-pipe},
-@code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Included
-Guile Modules}).
+@code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Pipes}).
Note in the previous example that if the current module had already
defined @code{open-pipe}, that definition would be overwritten by the
module to be accessed, but also selects bindings from it and renames
them to suit the current module's needs. For example:
-@smalllisp
+@cindex binding renamer
+@lisp
+(use-modules ((ice-9 popen)
+ #:select ((open-pipe . pipe-open) close-pipe)
+ #:renamer (symbol-prefix-proc 'unixy:)))
+@end lisp
+
+@noindent
+or more simply:
+
+@cindex prefix
+@lisp
(use-modules ((ice-9 popen)
- :select ((open-pipe . pipe-open) close-pipe)
- :renamer (symbol-prefix-proc 'unixy:)))
-@end smalllisp
+ #:select ((open-pipe . pipe-open) close-pipe)
+ #:prefix unixy:))
+@end lisp
Here, the interface specification is more complex than before, and the
result is that a custom interface with only two bindings is created and
open-pipe)}. Thus an alternative to the complete @code{use-modules}
statement would be
-@smalllisp
+@lisp
(define unixy:pipe-open (@@ (ice-9 popen) open-pipe))
(define unixy:close-pipe (@@ (ice-9 popen) close-pipe))
-@end smalllisp
+@end lisp
There is also @code{@@@@}, which can be used like @code{@@}, but does
not check whether the variable that is being accessed is actually
You can also use the @code{@@} and @code{@@@@} syntaxes as the target
of a @code{set!} when the binding refers to a variable.
-@c begin (scm-doc-string "boot-9.scm" "symbol-prefix-proc")
@deffn {Scheme Procedure} symbol-prefix-proc prefix-sym
Return a procedure that prefixes its arg (a symbol) with
@var{prefix-sym}.
-@c Insert gratuitous C++ slam here. --ttn
@end deffn
-@c begin (scm-doc-string "boot-9.scm" "use-modules")
@deffn syntax use-modules spec @dots{}
Resolve each interface specification @var{spec} into an interface and
arrange for these to be accessible by the current module. The return
@var{spec} can also be of the form:
-@smalllisp
- (MODULE-NAME [:select SELECTION] [:renamer RENAMER])
-@end smalllisp
+@cindex binding renamer
+@lisp
+ (MODULE-NAME [#:select SELECTION]
+ [#:prefix PREFIX]
+ [#:renamer RENAMER])
+@end lisp
in which case a custom interface is newly created and used.
@var{module-name} is a list of symbols, as above; @var{selection} is a
-list of selection-specs; and @var{renamer} is a procedure that takes a
-symbol and returns its new name. A selection-spec is either a symbol or
-a pair of symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in
-the used module and @var{seen} is the name in the using module. Note
-that @var{seen} is also passed through @var{renamer}.
-
-The @code{:select} and @code{:renamer} clauses are optional. If both are
-omitted, the returned interface has no bindings. If the @code{:select}
-clause is omitted, @var{renamer} operates on the used module's public
-interface.
-
-Signal error if module name is not resolvable.
-@end deffn
+list of selection-specs; @var{prefix} is a symbol that is prepended to
+imported names; and @var{renamer} is a procedure that takes a symbol and
+returns its new name. A selection-spec is either a symbol or a pair of
+symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in the used
+module and @var{seen} is the name in the using module. Note that
+@var{seen} is also modified by @var{prefix} and @var{renamer}.
+
+The @code{#:select}, @code{#:prefix}, and @code{#:renamer} clauses are
+optional. If all are omitted, the returned interface has no bindings.
+If the @code{#:select} clause is omitted, @var{prefix} and @var{renamer}
+operate on the used module's public interface.
+In addition to the above, @var{spec} can also include a @code{#:version}
+clause, of the form:
+
+@lisp
+ #:version VERSION-SPEC
+@end lisp
-@c FIXME::martin: Is this correct, and is there more to say?
-@c FIXME::martin: Define term and concept `system transformer' somewhere.
+where @var{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 @var{version-spec}. @xref{R6RS Version
+References}, for more on version references.
-@deffn syntax use-syntax module-name
-Load the module @code{module-name} and use its system
-transformer as the system transformer for the currently defined module,
-as well as installing it as the current system transformer.
+If the module name is not resolvable, @code{use-modules} will signal an
+error.
@end deffn
@deffn syntax @@ module-name binding-name
@end deffn
@node Creating Guile Modules
-@subsubsection Creating Guile Modules
+@subsection Creating Guile Modules
When you want to create your own modules, you have to take the following
steps:
by using @code{define-public} or @code{export} (both documented below).
@end itemize
-@c begin (scm-doc-string "boot-9.scm" "define-module")
-@deffn syntax define-module module-name [options @dots{}]
-@var{module-name} is of the form @code{(hierarchy file)}. One
-example of this is
+@deffn syntax define-module module-name option @dots{}
+@var{module-name} is a list of one or more symbols.
-@smalllisp
+@lisp
(define-module (ice-9 popen))
-@end smalllisp
+@end lisp
@code{define-module} makes this module available to Guile programs under
the given @var{module-name}.
-The @var{options} are keyword/value pairs which specify more about the
-defined module. The recognized options and their meaning is shown in
+@var{option} @dots{} are keyword/value pairs which specify more about the
+defined module. The recognized options and their meaning are shown in
the following table.
-@c fixme: Should we use "#:" or ":"?
-
@table @code
@item #:use-module @var{interface-specification}
Equivalent to a @code{(use-modules @var{interface-specification})}
(@pxref{Using Guile Modules}).
-@item #:use-syntax @var{module}
-Use @var{module} when loading the currently defined module, and install
-it as the syntax transformer.
-
@item #:autoload @var{module} @var{symbol-list}
@cindex autoload
Load @var{module} when any of @var{symbol-list} are accessed. For
@item #:export @var{list}
@cindex export
-Export all identifiers in @var{list}, which must be a list of symbols.
-This is equivalent to @code{(export @var{list})} in the module body.
+Export all identifiers in @var{list} which must be a list of symbols
+or pairs of symbols. This is equivalent to @code{(export @var{list})}
+in the module body.
+
+@item #:re-export @var{list}
+@cindex re-export
+Re-export all identifiers in @var{list} which must be a list of
+symbols or pairs of symbols. The symbols in @var{list} must be
+imported by the current module from other modules. This is equivalent
+to @code{re-export} below.
+
+@item #:replace @var{list}
+@cindex replace
+@cindex replacing binding
+@cindex overriding binding
+@cindex duplicate binding
+Export all identifiers in @var{list} (a list of symbols or pairs of
+symbols) and mark them as @dfn{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,
+@code{#:replace} avoids that.
+
+In general, a module that exports a binding for which the @code{(guile)}
+module already has a definition should use @code{#:replace} instead of
+@code{#:export}. @code{#:replace}, in a sense, lets Guile know that the
+module @emph{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 @code{(guile)}, to avoid surprising
+the user, sometimes the bindings will be incompatible. For example,
+SRFI-19 exports its own version of @code{current-time} (@pxref{SRFI-19
+Time}) which is not compatible with the core @code{current-time}
+function (@pxref{Time}). Guile assumes that a user importing a module
+knows what she is doing, and uses @code{#:replace} for this binding
+rather than @code{#:export}.
+
+A @code{#:replace} clause is equivalent to @code{(export! @var{list})}
+in the module body.
+
+The @code{#:duplicates} (see below) provides fine-grain control about
+duplicate binding handling on the module-user side.
+
+@item #:version @var{list}
+@cindex module version
+Specify a version for the module in the form of @var{list}, a list of
+zero or more exact, nonnegative integers. The corresponding
+@code{#:version} option in the @code{use-modules} form allows callers
+to restrict the value of this option in various ways.
+
+@item #:duplicates @var{list}
+@cindex duplicate binding handlers
+@cindex duplicate binding
+@cindex overriding binding
+Tell Guile to handle duplicate bindings for the bindings imported by
+the current module according to the policy defined by @var{list}, a
+list of symbols. @var{list} must contain symbols representing a
+duplicate binding handling policy chosen among the following:
-@item #:no-backtrace
-@cindex no backtrace
-Tell Guile not to record information for procedure backtraces when
-executing the procedures in this module.
+@table @code
+@item check
+Raises an error when a binding is imported from more than one place.
+@item 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.
+@item replace
+When a new binding is imported that has the same name as a previously
+imported binding, then do the following:
+
+@enumerate
+@item
+@cindex replacing binding
+If the old binding was said to be @dfn{replacing} (via the
+@code{#:replace} option above) and the new binding is not replacing,
+the keep the old binding.
+@item
+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.
+@item
+If neither the old nor the new binding is replacing, then keep the old
+one.
+@end enumerate
+
+@item warn-override-core
+Issue a warning when a core binding is being overwritten and actually
+override the core binding with the new one.
+@item first
+In case of duplicate bindings, the firstly imported binding is always
+the one which is kept.
+@item last
+In case of duplicate bindings, the lastly imported binding is always
+the one which is kept.
+@item noop
+In case of duplicate bindings, leave the responsibility to the next
+duplicate handler.
+@end table
+
+If @var{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 @var{list}.
+
+If GOOPS has been loaded before the @code{#:duplicates} clause is
+processed, there are additional strategies available for dealing with
+generic functions. @xref{Merging Generics}, for more information.
+
+@findex default-duplicate-binding-handler
+The default duplicate binding resolution policy is given by the
+@code{default-duplicate-binding-handler} procedure, and is
+
+@lisp
+(replace warn-override-core warn last)
+@end lisp
@item #:pure
@cindex pure module
@end table
@end deffn
-@c end
@deffn syntax export variable @dots{}
-Add all @var{variable}s (which must be symbols) to the list of exported
-bindings of the current module.
+Add all @var{variable}s (which must be symbols or pairs of symbols) to
+the list of exported bindings of the current module. If @var{variable}
+is a pair, its @code{car} gives the name of the variable as seen by the
+current module and its @code{cdr} specifies a name for the binding in
+the current module's public interface.
@end deffn
-@c begin (scm-doc-string "boot-9.scm" "define-public")
@deffn syntax define-public @dots{}
Equivalent to @code{(begin (define foo ...) (export foo))}.
@end deffn
-@c end
-@node Module System Reflection
-@subsubsection Module System Reflection
+@deffn syntax re-export variable @dots{}
+Add all @var{variable}s (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 @code{export}. Re-exported bindings must be
+imported by the current module from some other module.
+@end deffn
-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.
+@deffn syntax export! variable @dots{}
+Like @code{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
+@code{#:replace} above.
+@end deffn
-At any time, there is a @dfn{current module}. This module is the one
-where a top-level @code{define} and similar syntax will add new
-bindings. You can find other module objects with @code{resolve-module},
-for example.
+@node Modules and the File System
+@subsection Modules and the File System
+
+Typical programs only use a small subset of modules installed on a Guile
+system. In order to keep startup time down, Guile only loads modules
+when a program uses them, on demand.
+
+When a program evaluates @code{(use-modules (ice-9 popen))}, and the
+module is not loaded, Guile searches for a conventionally-named file
+from in the @dfn{load path}.
+
+In this case, loading @code{(ice-9 popen)} will eventually cause Guile
+to run @code{(primitive-load-path "ice-9/popen")}.
+@code{primitive-load-path} will search for a file @file{ice-9/popen} in
+the @code{%load-path} (@pxref{Load Paths}). For each directory in
+@code{%load-path}, Guile will try to find the file name, concatenated
+with the extensions from @code{%load-extensions}. By default, this will
+cause Guile to @code{stat} @file{ice-9/popen.scm}, and then
+@file{ice-9/popen}. @xref{Load Paths}, for more on
+@code{primitive-load-path}.
+
+If a corresponding compiled @file{.go} file is found in the
+@code{%load-compiled-path} or in the fallback path, and is as fresh as
+the source file, it will be loaded instead of the source file. If no
+compiled file is found, Guile may try to compile the source file and
+cache away the resulting @file{.go} file. @xref{Compilation}, for more
+on compilation.
+
+Once Guile finds a suitable source or compiled file is found, the file
+will be loaded. If, after loading the file, the module under
+consideration is still not defined, Guile will signal an error.
+
+For more information on where and how to install Scheme modules,
+@xref{Installing Site Packages}.
+
+
+@node R6RS Version References
+@subsection R6RS Version References
+
+Guile's module system includes support for locating modules based on
+a declared version specifier of the same form as the one described in
+R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The Revised^6
+Report on the Algorithmic Language Scheme}). By using the
+@code{#:version} keyword in a @code{define-module} form, a module may
+specify a version as a list of zero or more exact, nonnegative integers.
+
+This version can then be used to locate the module during the module
+search process. Client modules and callers of the @code{use-modules}
+function may specify constraints on the versions of target modules by
+providing a @dfn{version reference}, which has one of the following
+forms:
-These module objects can be used as the second argument to @code{eval}.
+@lisp
+ (@var{sub-version-reference} ...)
+ (and @var{version-reference} ...)
+ (or @var{version-reference} ...)
+ (not @var{version-reference})
+@end lisp
-@deffn {Scheme Procedure} current-module
-Return the current module object.
-@end deffn
+in which @var{sub-version-reference} is in turn one of:
-@deffn {Scheme Procedure} set-current-module module
-Set the current module to @var{module} and return
-the previous current module.
-@end deffn
+@lisp
+ (@var{sub-version})
+ (>= @var{sub-version})
+ (<= @var{sub-version})
+ (and @var{sub-version-reference} ...)
+ (or @var{sub-version-reference} ...)
+ (not @var{sub-version-reference})
+@end lisp
-@deffn {Scheme Procedure} resolve-module name
-Find the module named @var{name} and return it. When it has not already
-been defined, try to auto-load it. When it can't be found that way
-either, create an empty module. The name is a list of symbols.
-@end deffn
+in which @var{sub-version} is an exact, nonnegative integer as above. A
+version reference matches a declared module version if each element of
+the version reference matches a corresponding element of the module
+version, according to the following rules:
-@deffn {Scheme Procedure} resolve-interface name
-Find the module named @var{name} as with @code{resolve-module} and
-return its interface. The interface of a module is also a module
-object, but it contains only the exported bindings.
-@end deffn
+@itemize @bullet
+@item
+The @code{and} sub-form matches a version or version element if every
+element in the tail of the sub-form matches the specified version or
+version element.
-@deffn {Scheme Procedure} module-use! module interface
-Add @var{interface} to the front of the use-list of @var{module}. Both
-arguments should be module objects, and @var{interface} should very
-likely be a module returned by @code{resolve-interface}.
-@end deffn
+@item
+The @code{or} sub-form matches a version or version element if any
+element in the tail of the sub-form matches the specified version or
+version element.
+
+@item
+The @code{not} sub-form matches a version or version element if the tail
+of the sub-form does not match the version or version element.
+
+@item
+The @code{>=} sub-form matches a version element if the element is
+greater than or equal to the @var{sub-version} in the tail of the
+sub-form.
+
+@item
+The @code{<=} sub-form matches a version element if the version is less
+than or equal to the @var{sub-version} in the tail of the sub-form.
+
+@item
+A @var{sub-version} matches a version element if one is @var{eqv?} to
+the other.
+@end itemize
+
+For example, a module declared as:
+
+@lisp
+ (define-module (mylib mymodule) #:version (1 2 0))
+@end lisp
+
+would be successfully loaded by any of the following @code{use-modules}
+expressions:
+
+@lisp
+ (use-modules ((mylib mymodule) #:version (1 2 (>= 0))))
+ (use-modules ((mylib mymodule) #:version (or (1 2 0) (1 2 1))))
+ (use-modules ((mylib mymodule) #:version ((and (>= 1) (not 2)) 2 0)))
+@end lisp
+
+
+@node R6RS Libraries
+@subsection R6RS Libraries
+
+In addition to the API described in the previous sections, you also
+have the option to create modules using the portable @code{library} form
+described in R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The
+Revised^6 Report on the Algorithmic Language Scheme}), and to import
+libraries created in this format by other programmers. Guile's R6RS
+library implementation takes advantage of the flexibility built into the
+module system by expanding the R6RS library form into a corresponding
+Guile @code{define-module} form that specifies equivalent import and
+export requirements and includes the same body expressions. The library
+expression:
+
+@lisp
+ (library (mylib (1 2))
+ (export mybinding)
+ (import (otherlib (3))))
+@end lisp
+
+is equivalent to the module definition:
+
+@lisp
+ (define-module (mylib)
+ #:version (1 2)
+ #:use-module ((otherlib) #:version (3))
+ #:export (mybinding))
+@end lisp
+
+Central to the mechanics of R6RS libraries is the concept of import
+and export @dfn{levels}, which control the visibility of bindings at
+various phases of a library's lifecycle --- macros necessary to
+expand forms in the library's body need to be available at expand
+time; variables used in the body of a procedure exported by the
+library must be available at runtime. R6RS specifies the optional
+@code{for} sub-form of an @emph{import set} specification (see below)
+as a mechanism by which a library author can indicate that a
+particular library import should take place at a particular phase
+with respect to the lifecycle of the importing library.
+
+Guile's library implementation uses a technique called
+@dfn{implicit phasing} (first described by Abdulaziz Ghuloum and R.
+Kent Dybvig), which allows the expander and compiler to automatically
+determine the necessary visibility of a binding imported from another
+library. As such, the @code{for} sub-form described below is ignored by
+Guile (but may be required by Schemes in which phasing is explicit).
+
+@deffn {Scheme Syntax} library name (export export-spec ...) (import import-spec ...) body ...
+Defines a new library with the specified name, exports, and imports,
+and evaluates the specified body expressions in this library's
+environment.
+
+The library @var{name} is a non-empty list of identifiers, optionally
+ending with a version specification of the form described above
+(@pxref{Creating Guile Modules}).
+
+Each @var{export-spec} is the name of a variable defined or imported
+by the library, or must take the form
+@code{(rename (internal-name external-name) ...)}, where the
+identifier @var{internal-name} names a variable defined or imported
+by the library and @var{external-name} is the name by which the
+variable is seen by importing libraries.
+
+Each @var{import-spec} must be either an @dfn{import set} (see below)
+or must be of the form @code{(for import-set import-level ...)},
+where each @var{import-level} is one of:
+
+@lisp
+ run
+ expand
+ (meta @var{level})
+@end lisp
+
+where @var{level} is an integer. Note that since Guile does not
+require explicit phase specification, any @var{import-set}s found
+inside of @code{for} sub-forms will be ``unwrapped'' during
+expansion and processed as if they had been specified directly.
+
+Import sets in turn take one of the following forms:
-@node Module System Quirks
-@subsubsection Module System Quirks
+@lisp
+ @var{library-reference}
+ (library @var{library-reference})
+ (only @var{import-set} @var{identifier} ...)
+ (except @var{import-set} @var{identifier} ...)
+ (prefix @var{import-set} @var{identifier})
+ (rename @var{import-set} (@var{internal-identifier} @var{external-identifier}) ...)
+@end lisp
-Although the programming interfaces are relatively stable, the Guile
-module system itself is still evolving. Here are some situations where
-usage surpasses design.
+where @var{library-reference} is a non-empty list of identifiers
+ending with an optional version reference (@pxref{R6RS Version
+References}), and the other sub-forms have the following semantics,
+defined recursively on nested @var{import-set}s:
@itemize @bullet
@item
-When using a module which exports a macro definition, the other module
-must export all bindings the macro expansion uses, too, because the
-expanded code would otherwise not be able to see these definitions and
-issue a ``variable unbound'' error, or worse, would use another binding
-which might be present in the scope of the expansion.
+The @code{library} sub-form is used to specify libraries for import
+whose names begin with the identifier ``library.''
+
+@item
+The @code{only} sub-form imports only the specified @var{identifier}s
+from the given @var{import-set}.
@item
-When two or more used modules export bindings with the same names, the
-last accessed module wins, and the exported binding of that last module
-will silently be used. This might lead to hard-to-find errors because
-wrong procedures or variables are used. To avoid this kind of
-@dfn{name-clash} situation, use a custom interface specification
-(@pxref{Using Guile Modules}). (We include this entry for the possible
-benefit of users of Guile versions previous to 1.5.0, when custom
-interfaces were added to the module system.)
+The @code{except} sub-form imports all of the bindings exported by
+@var{import-set} except for those that appear in the specified list
+of @var{identifier}s.
@item
-[Add other quirks here.]
+The @code{prefix} sub-form imports all of the bindings exported
+by @var{import-set}, first prefixing them with the specified
+@var{identifier}.
+
+@item
+The @code{rename} sub-form imports all of the identifiers exported
+by @var{import-set}. The binding for each @var{internal-identifier}
+among these identifiers is made visible to the importing library as
+the corresponding @var{external-identifier}; all other bindings are
+imported using the names provided by @var{import-set}.
@end itemize
+Note that because Guile translates R6RS libraries into module
+definitions, an import specification may be used to declare a
+dependency on a native Guile module --- although doing so may make
+your libraries less portable to other Schemes.
-@node Included Guile Modules
-@subsubsection Included Guile Modules
+@end deffn
-@c FIXME::martin: Review me!
+@deffn {Scheme Syntax} import import-spec ...
+Import into the current environment the libraries specified by the
+given import specifications, where each @var{import-spec} takes the
+same form as in the @code{library} form described above.
+@end deffn
-Some modules are included in the Guile distribution; here are references
-to the entries in this manual which describe them in more detail:
-@table @strong
-@item boot-9
-boot-9 is Guile's initialization module, and it is always loaded when
-Guile starts up.
+@node Variables
+@subsection Variables
+@tpindex Variables
-@item (ice-9 debug)
-Mikael Djurfeldt's source-level debugging support for Guile
-(@pxref{Debugging Features}).
+Each module has its own hash table, sometimes known as an @dfn{obarray},
+that maps the names defined in that module to their corresponding
+variable objects.
-@item (ice-9 expect)
-Actions based on matching input from a port (@pxref{Expect}).
+A variable is a box-like object that can hold any Scheme value. It is
+said to be @dfn{undefined} if its box holds a special Scheme value that
+denotes undefined-ness (which is different from all other Scheme values,
+including for example @code{#f}); otherwise the variable is
+@dfn{defined}.
-@item (ice-9 format)
-Formatted output in the style of Common Lisp (@pxref{Formatted
-Output}).
+On its own, a variable object is anonymous. A variable is said to be
+@dfn{bound} when it is associated with a name in some way, usually a
+symbol in a module obarray. When this happens, the name is said to be
+bound to the variable, in that module.
-@item (ice-9 ftw)
-File tree walker (@pxref{File Tree Walk}).
+(That's the theory, anyway. In practice, defined-ness and bound-ness
+sometimes get confused, because Lisp and Scheme implementations have
+often conflated --- or deliberately drawn no distinction between --- a
+name that is unbound and a name that is bound to a variable whose value
+is undefined. We will try to be clear about the difference and explain
+any confusion where it is unavoidable.)
-@item (ice-9 getopt-long)
-Command line option processing (@pxref{getopt-long}).
+Variables do not have a read syntax. Most commonly they are created and
+bound implicitly by @code{define} expressions: a top-level @code{define}
+expression of the form
-@item (ice-9 history)
-Refer to previous interactive expressions (@pxref{Value History}).
+@lisp
+(define @var{name} @var{value})
+@end lisp
-@item (ice-9 popen)
-Pipes to and from child processes (@pxref{Pipes}).
+@noindent
+creates a variable with initial value @var{value} and binds it to the
+name @var{name} in the current module. But they can also be created
+dynamically by calling one of the constructor procedures
+@code{make-variable} and @code{make-undefined-variable}.
-@item (ice-9 pretty-print)
-Nicely formatted output of Scheme expressions and objects
-(@pxref{Pretty Printing}).
+@deffn {Scheme Procedure} make-undefined-variable
+@deffnx {C Function} scm_make_undefined_variable ()
+Return a variable that is initially unbound.
+@end deffn
-@item (ice-9 q)
-First-in first-out queues (@pxref{Queues}).
+@deffn {Scheme Procedure} make-variable init
+@deffnx {C Function} scm_make_variable (init)
+Return a variable initialized to value @var{init}.
+@end deffn
-@item (ice-9 rdelim)
-Line- and character-delimited input (@pxref{Line/Delimited}).
+@deffn {Scheme Procedure} variable-bound? var
+@deffnx {C Function} scm_variable_bound_p (var)
+Return @code{#t} if @var{var} is bound to a value, or @code{#f}
+otherwise. Throws an error if @var{var} is not a variable object.
+@end deffn
-@item (ice-9 readline)
-@code{readline} interactive command line editing (@pxref{Readline
-Support}).
+@deffn {Scheme Procedure} variable-ref var
+@deffnx {C Function} scm_variable_ref (var)
+Dereference @var{var} and return its value.
+@var{var} must be a variable object; see @code{make-variable}
+and @code{make-undefined-variable}.
+@end deffn
-@item (ice-9 receive)
-Multiple-value handling with @code{receive} (@pxref{Multiple Values}).
+@deffn {Scheme Procedure} variable-set! var val
+@deffnx {C Function} scm_variable_set_x (var, val)
+Set the value of the variable @var{var} to @var{val}.
+@var{var} must be a variable object, @var{val} can be any
+value. Return an unspecified value.
+@end deffn
-@item (ice-9 regex)
-Regular expression matching (@pxref{Regular Expressions}).
+@deffn {Scheme Procedure} variable-unset! var
+@deffnx {C Function} scm_variable_unset_x (var)
+Unset the value of the variable @var{var}, leaving @var{var} unbound.
+@end deffn
-@item (ice-9 rw)
-Block string input/output (@pxref{Block Reading and Writing}).
+@deffn {Scheme Procedure} variable? obj
+@deffnx {C Function} scm_variable_p (obj)
+Return @code{#t} if @var{obj} is a variable object, else return
+@code{#f}.
+@end deffn
-@item (ice-9 streams)
-Sequence of values calculated on-demand (@pxref{Streams}).
-@item (ice-9 syncase)
-R5RS @code{syntax-rules} macro system (@pxref{Syntax Rules}).
+@node Module System Reflection
+@subsection Module System Reflection
-@item (ice-9 threads)
-Guile's support for multi threaded execution (@pxref{Scheduling}).
+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.
-@item (ice-9 documentation)
-Online documentation (REFFIXME).
+At any time, there is a @dfn{current module}. This module is the one
+where a top-level @code{define} and similar syntax will add new
+bindings. You can find other module objects with @code{resolve-module},
+for example.
-@item (srfi srfi-1)
-A library providing a lot of useful list and pair processing
-procedures (@pxref{SRFI-1}).
+These module objects can be used as the second argument to @code{eval}.
-@item (srfi srfi-2)
-Support for @code{and-let*} (@pxref{SRFI-2}).
+@deffn {Scheme Procedure} current-module
+@deffnx {C Function} scm_current_module ()
+Return the current module object.
+@end deffn
-@item (srfi srfi-4)
-Support for homogeneous numeric vectors (@pxref{SRFI-4}).
+@deffn {Scheme Procedure} set-current-module module
+@deffnx {C Function} scm_set_current_module (module)
+Set the current module to @var{module} and return
+the previous current module.
+@end deffn
-@item (srfi srfi-6)
-Support for some additional string port procedures (@pxref{SRFI-6}).
+@deffn {Scheme Procedure} save-module-excursion thunk
+Call @var{thunk} within a @code{dynamic-wind} such that the module that
+is current at invocation time is restored when @var{thunk}'s dynamic
+extent is left (@pxref{Dynamic Wind}).
-@item (srfi srfi-8)
-Multiple-value handling with @code{receive} (@pxref{SRFI-8}).
+More precisely, if @var{thunk} escapes non-locally, the current module
+(at the time of escape) is saved, and the original current module (at
+the time @var{thunk}'s dynamic extent was last entered) is restored. If
+@var{thunk}'s dynamic extent is re-entered, then the current module is
+saved, and the previously saved inner module is set current again.
+@end deffn
-@item (srfi srfi-9)
-Record definition with @code{define-record-type} (@pxref{SRFI-9}).
+@deffn {Scheme Procedure} resolve-module name [autoload=#t] [version=#f] @
+ [#:ensure=#t]
+@deffnx {C Function} scm_resolve_module (name)
+Find the module named @var{name} and return it. When it has not already
+been defined and @var{autoload} is true, try to auto-load it. When it
+can't be found that way either, create an empty module if @var{ensure}
+is true, otherwise return @code{#f}. If @var{version} is true, ensure
+that the resulting module is compatible with the given version reference
+(@pxref{R6RS Version References}). The name is a list of symbols.
+@end deffn
-@item (srfi srfi-10)
-Read hash extension @code{#,()} (@pxref{SRFI-10}).
+@deffn {Scheme Procedure} resolve-interface name [#:select=#f] @
+ [#:hide='()] [#:prefix=#f] @
+ [#:renamer=#f] [#:version=#f]
+Find the module named @var{name} as with @code{resolve-module} and
+return its interface. The interface of a module is also a module
+object, but it contains only the exported bindings.
+@end deffn
-@item (srfi srfi-11)
-Multiple-value handling with @code{let-values} and @code{let-values*}
-(@pxref{SRFI-11}).
+@deffn {Scheme Procedure} module-uses module
+Return a list of the interfaces used by @var{module}.
+@end deffn
-@item (srfi srfi-13)
-String library (@pxref{SRFI-13}).
+@deffn {Scheme Procedure} module-use! module interface
+Add @var{interface} to the front of the use-list of @var{module}. Both
+arguments should be module objects, and @var{interface} should very
+likely be a module returned by @code{resolve-interface}.
+@end deffn
-@item (srfi srfi-14)
-Character-set library (@pxref{SRFI-14}).
+@deffn {Scheme Procedure} reload-module module
+Revisit the source file that corresponds to @var{module}. Raises an
+error if no source file is associated with the given module.
+@end deffn
+
+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, @ref{Accessing Modules from C}.
-@item (srfi srfi-16)
-@code{case-lambda} procedures of variable arity (@pxref{SRFI-16}).
+@deffn {Scheme Procedure} module-variable module name
+Return the variable bound to @var{name} (a symbol) in @var{module}, or
+@code{#f} if @var{name} is unbound.
+@end deffn
-@item (srfi srfi-17)
-Getter-with-setter support (@pxref{SRFI-17}).
+@deffn {Scheme Procedure} module-add! module name var
+Define a new binding between @var{name} (a symbol) and @var{var} (a
+variable) in @var{module}.
+@end deffn
-@item (srfi srfi-19)
-Time/Date library (@pxref{SRFI-19}).
+@deffn {Scheme Procedure} module-ref module name
+Look up the value bound to @var{name} in @var{module}. Like
+@code{module-variable}, but also does a @code{variable-ref} on the
+resulting variable, raising an error if @var{name} is unbound.
+@end deffn
-@item (srfi srfi-26)
-Convenient syntax for partial application (@pxref{SRFI-26})
+@deffn {Scheme Procedure} module-define! module name value
+Locally bind @var{name} to @var{value} in @var{module}. If @var{name}
+was already locally bound in @var{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
+@code{module-add!}.
+@end deffn
-@item (srfi srfi-31)
-@code{rec} convenient recursive expressions (@pxref{SRFI-31})
+@deffn {Scheme Procedure} module-set! module name value
+Update the binding of @var{name} in @var{module} to @var{value}, raising
+an error if @var{name} is not already bound in @var{module}.
+@end deffn
-@item (ice-9 slib)
-This module contains hooks for using Aubrey Jaffer's portable Scheme
-library SLIB from Guile (@pxref{SLIB}).
-@end table
+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.
@node Accessing Modules from C
-@subsubsection Accessing Modules from C
+@subsection Accessing Modules from C
The last sections have described how modules are used in Scheme code,
which is the recommended way of creating and accessing modules. You
The following procedures are available.
-@deftypefn {C Procedure} SCM scm_current_module ()
-Return the module that is the @emph{current module}.
-@end deftypefn
-
-@deftypefn {C Procedure} SCM scm_set_current_module (SCM @var{module})
-Set the current module to @var{module} and return the previous current
-module.
-@end deftypefn
-
-@deftypefn {C Procedure} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data})
+@deftypefn {C Function} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data})
Call @var{func} and make @var{module} the current module during the
call. The argument @var{data} is passed to @var{func}. The return
value of @code{scm_c_call_with_current_module} is the return value of
@var{func}.
@end deftypefn
-@deftypefn {C Procedure} SCM scm_c_lookup (const char *@var{name})
+@deftypefn {C Function} SCM scm_public_variable (SCM @var{module_name}, SCM @var{name})
+@deftypefnx {C Function} SCM scm_c_public_variable ({const char *}@var{module_name}, {const char *}@var{name})
+Find a the variable bound to the symbol @var{name} in the public
+interface of the module named @var{module_name}.
+
+@var{module_name} should be a list of symbols, when represented as a
+Scheme object, or a space-separated string, in the @code{const char *}
+case. See @code{scm_c_define_module} below, for more examples.
+
+Signals an error if no module was found with the given name. If
+@var{name} is not bound in the module, just returns @code{#f}.
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_private_variable (SCM @var{module_name}, SCM @var{name})
+@deftypefnx {C Function} SCM scm_c_private_variable ({const char *}@var{module_name}, {const char *}@var{name})
+Like @code{scm_public_variable}, but looks in the internals of the
+module named @var{module_name} instead of the public interface.
+Logically, these procedures should only be called on modules you write.
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_public_lookup (SCM @var{module_name}, SCM @var{name})
+@deftypefnx {C Function} SCM scm_c_public_lookup ({const char *}@var{module_name}, {const char *}@var{name})
+@deftypefnx {C Function} SCM scm_private_lookup (SCM @var{module_name}, SCM @var{name})
+@deftypefnx {C Function} SCM scm_c_private_lookup ({const char *}@var{module_name}, {const char *}@var{name})
+Like @code{scm_public_variable} or @code{scm_private_variable}, but if
+the @var{name} is not bound in the module, signals an error. Returns a
+variable, always.
+
+@example
+static SCM eval_string_var;
+
+/* NOTE: It is important that the call to 'my_init'
+ happens-before all calls to 'my_eval_string'. */
+void my_init (void)
+@{
+ eval_string_var = scm_c_public_lookup ("ice-9 eval-string",
+ "eval-string");
+@}
+
+SCM my_eval_string (SCM str)
+@{
+ return scm_call_1 (scm_variable_ref (eval_string_var), str);
+@}
+@end example
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_public_ref (SCM @var{module_name}, SCM @var{name})
+@deftypefnx {C Function} SCM scm_c_public_ref ({const char *}@var{module_name}, {const char *}@var{name})
+@deftypefnx {C Function} SCM scm_private_ref (SCM @var{module_name}, SCM @var{name})
+@deftypefnx {C Function} SCM scm_c_private_ref ({const char *}@var{module_name}, {const char *}@var{name})
+Like @code{scm_public_lookup} or @code{scm_private_lookup}, but
+additionally dereferences the variable. If the variable object is
+unbound, signals an error. Returns the value bound to @var{name} in
+@var{module_name}.
+@end deftypefn
+
+In addition, there are a number of other lookup-related procedures. We
+suggest that you use the @code{scm_public_} and @code{scm_private_}
+family of procedures instead, if possible.
+
+@deftypefn {C Function} SCM scm_c_lookup ({const char *}@var{name})
Return the variable bound to the symbol indicated by @var{name} in the
current module. If there is no such binding or the symbol is not
bound to a variable, signal an error.
@end deftypefn
-@deftypefn {C Procedure} SCM scm_lookup (SCM @var{name})
+@deftypefn {C Function} SCM scm_lookup (SCM @var{name})
Like @code{scm_c_lookup}, but the symbol is specified directly.
@end deftypefn
-@deftypefn {C Procedure} SCM scm_c_module_lookup (SCM @var{module}, const char *@var{name})
-@deftypefnx {C Procedure} SCM scm_module_lookup (SCM @var{module}, SCM @var{name})
+@deftypefn {C Function} SCM scm_c_module_lookup (SCM @var{module}, {const char *}@var{name})
+@deftypefnx {C Function} SCM scm_module_lookup (SCM @var{module}, SCM @var{name})
Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified
module is used instead of the current one.
@end deftypefn
-@deftypefn {C Procedure} SCM scm_c_define (const char *@var{name}, SCM @var{val})
+@deftypefn {C Function} SCM scm_module_variable (SCM @var{module}, SCM @var{name})
+Like @code{scm_module_lookup}, but if the binding does not exist, just
+returns @code{#f} instead of raising an error.
+@end deftypefn
+
+To define a value, use @code{scm_define}:
+
+@deftypefn {C Function} SCM scm_c_define ({const char *}@var{name}, SCM @var{val})
Bind the symbol indicated by @var{name} to a variable in the current
module and set that variable to @var{val}. When @var{name} is already
bound to a variable, use that. Else create a new variable.
@end deftypefn
-@deftypefn {C Procedure} SCM scm_define (SCM @var{name}, SCM @var{val})
+@deftypefn {C Function} SCM scm_define (SCM @var{name}, SCM @var{val})
Like @code{scm_c_define}, but the symbol is specified directly.
@end deftypefn
-@deftypefn {C Procedure} SCM scm_c_module_define (SCM @var{module}, const char *@var{name}, SCM @var{val})
-@deftypefnx {C Procedure} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val})
+@deftypefn {C Function} SCM scm_c_module_define (SCM @var{module}, {const char *}@var{name}, SCM @var{val})
+@deftypefnx {C Function} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val})
Like @code{scm_c_define} and @code{scm_define}, but the specified
module is used instead of the current one.
@end deftypefn
-@deftypefn {C Procedure} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable})
-Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @var{#f}.
+In some rare cases, you may need to access the variable that
+@code{scm_module_define} would have accessed, without changing the
+binding of the existing variable, if one is present. In that case, use
+@code{scm_module_ensure_local_variable}:
+
+@deftypefn {C Function} SCM scm_module_ensure_local_variable (SCM @var{module}, SCM @var{sym})
+Like @code{scm_module_define}, but if the @var{sym} is already locally
+bound in that module, the variable's existing binding is not reset.
+Returns a variable.
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable})
+Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @code{#f}.
@end deftypefn
-@deftypefn {C Procedure} SCM scm_c_define_module (const char *@var{name}, void (*@var{init})(void *), void *@var{data})
+@deftypefn {C Function} SCM scm_c_define_module ({const char *}@var{name}, void (*@var{init})(void *), void *@var{data})
Define a new module named @var{name} and make it current while
@var{init} is called, passing it @var{data}. Return the module.
unchanged, otherwise, an empty module is created.
@end deftypefn
-@deftypefn {C Procedure} SCM scm_c_resolve_module (const char *@var{name})
+@deftypefn {C Function} SCM scm_c_resolve_module ({const char *}@var{name})
Find the module name @var{name} and return it. When it has not
already been defined, try to auto-load it. When it can't be found
that way either, create an empty module. The name is interpreted as
for @code{scm_c_define_module}.
@end deftypefn
-@deftypefn {C Procedure} SCM scm_resolve_module (SCM @var{name})
-Like @code{scm_c_resolve_module}, but the name is given as a real list
-of symbols.
-@end deftypefn
-
-@deftypefn {C Procedure} SCM scm_c_use_module (const char *@var{name})
+@deftypefn {C Function} SCM scm_c_use_module ({const char *}@var{name})
Add the module named @var{name} to the uses list of the current
module, as with @code{(use-modules @var{name})}. The name is
interpreted as for @code{scm_c_define_module}.
@end deftypefn
-@deftypefn {C Procedure} SCM scm_c_export (const char *@var{name}, ...)
+@deftypefn {C Function} void scm_c_export ({const char *}@var{name}, ...)
Add the bindings designated by @var{name}, ... to the public interface
of the current module. The list of names is terminated by
@code{NULL}.
@end deftypefn
-@node Dynamic Libraries
-@subsection Dynamic Libraries
-
-Most modern Unices have something called @dfn{shared libraries}. This
-ordinarily means that they have the capability to share the executable
-image of a library between several running programs to save memory and
-disk space. But generally, shared libraries give a lot of additional
-flexibility compared to the traditional static libraries. In fact,
-calling them `dynamic' libraries is as correct as calling them `shared'.
-
-Shared libraries really give you a lot of flexibility in addition to the
-memory and disk space savings. When you link a program against a shared
-library, that library is not closely incorporated into the final
-executable. Instead, the executable of your program only contains
-enough information to find the needed shared libraries when the program
-is actually run. Only then, when the program is starting, is the final
-step of the linking process performed. This means that you need not
-recompile all programs when you install a new, only slightly modified
-version of a shared library. The programs will pick up the changes
-automatically the next time they are run.
-
-Now, when all the necessary machinery is there to perform part of the
-linking at run-time, why not take the next step and allow the programmer
-to explicitly take advantage of it from within his program? Of course,
-many operating systems that support shared libraries do just that, and
-chances are that Guile will allow you to access this feature from within
-your Scheme programs. As you might have guessed already, this feature
-is called @dfn{dynamic linking}.@footnote{Some people also refer to the
-final linking stage at program startup as `dynamic linking', so if you
-want to make yourself perfectly clear, it is probably best to use the
-more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit
-in his libtool documentation.}
-
-As with many aspects of Guile, there is a low-level way to access the
-dynamic linking apparatus, and a more high-level interface that
-integrates dynamically linked libraries into the module system.
-
-@menu
-* Low level dynamic linking::
-* Compiled Code Modules::
-* Dynamic Linking and Compiled Code Modules::
-@end menu
-
-@node Low level dynamic linking
-@subsubsection Low level dynamic linking
-
-When using the low level procedures to do your dynamic linking, you have
-complete control over which library is loaded when and what gets done
-with it.
-
-@deffn {Scheme Procedure} dynamic-link library
-@deffnx {C Function} scm_dynamic_link (library)
-Find the shared library denoted by @var{library} (a string) and link it
-into the running Guile application. When everything works out, return a
-Scheme object suitable for representing the linked object file.
-Otherwise an error is thrown. How object files are searched is system
-dependent.
-
-Normally, @var{library} is just the name of some shared library file
-that will be searched for in the places where shared libraries usually
-reside, such as in @file{/usr/lib} and @file{/usr/local/lib}.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-object? obj
-@deffnx {C Function} scm_dynamic_object_p (obj)
-Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-unlink dobj
-@deffnx {C Function} scm_dynamic_unlink (dobj)
-Unlink the indicated object file from the application. The
-argument @var{dobj} must have been obtained by a call to
-@code{dynamic-link}. After @code{dynamic-unlink} has been
-called on @var{dobj}, its content is no longer accessible.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-func name dobj
-@deffnx {C Function} scm_dynamic_func (name, dobj)
-Search the dynamic object @var{dobj} for the C function
-indicated by the string @var{name} and return some Scheme
-handle that can later be used with @code{dynamic-call} to
-actually call the function.
-
-Regardless whether your C compiler prepends an underscore @samp{_} to
-the global names in a program, you should @strong{not} include this
-underscore in @var{function}. Guile knows whether the underscore is
-needed or not and will add it when necessary.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-call func dobj
-@deffnx {C Function} scm_dynamic_call (func, dobj)
-Call the C function indicated by @var{func} and @var{dobj}.
-The function is passed no arguments and its return value is
-ignored. When @var{function} is something returned by
-@code{dynamic-func}, call that function and ignore @var{dobj}.
-When @var{func} is a string , look it up in @var{dynobj}; this
-is equivalent to
-@smallexample
-(dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
-@end smallexample
-
-Interrupts are deferred while the C function is executing (with
-@code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
-@end deffn
-@deffn {Scheme Procedure} dynamic-args-call func dobj args
-@deffnx {C Function} scm_dynamic_args_call (func, dobj, args)
-Call the C function indicated by @var{func} and @var{dobj},
-just like @code{dynamic-call}, but pass it some arguments and
-return its return value. The C function is expected to take
-two arguments and return an @code{int}, just like @code{main}:
-@smallexample
-int c_func (int argc, char **argv);
-@end smallexample
-
-The parameter @var{args} must be a list of strings and is
-converted into an array of @code{char *}. The array is passed
-in @var{argv} and its size in @var{argc}. The return value is
-converted to a Scheme number and returned from the call to
-@code{dynamic-args-call}.
-@end deffn
-
-When dynamic linking is disabled or not supported on your system,
-the above functions throw errors, but they are still available.
-
-Here is a small example that works on GNU/Linux:
-
-@smallexample
-(define libc-obj (dynamic-link "libc.so"))
-libc-obj
-@result{} #<dynamic-object "libc.so">
-(dynamic-args-call 'rand libc-obj '())
-@result{} 269167349
-(dynamic-unlink libc-obj)
-libc-obj
-@result{} #<dynamic-object "libc.so" (unlinked)>
-@end smallexample
-
-As you can see, after calling @code{dynamic-unlink} on a dynamically
-linked library, it is marked as @samp{(unlinked)} and you are no longer
-able to use it with @code{dynamic-call}, etc. Whether the library is
-really removed from you program is system-dependent and will generally
-not happen when some other parts of your program still use it. In the
-example above, @code{libc} is almost certainly not removed from your
-program because it is badly needed by almost everything.
-
-The functions to call a function from a dynamically linked library,
-@code{dynamic-call} and @code{dynamic-args-call}, are not very powerful.
-They are mostly intended to be used for calling specially written
-initialization functions that will then add new primitives to Guile.
-For example, we do not expect that you will dynamically link
-@file{libX11} with @code{dynamic-link} and then construct a beautiful
-graphical user interface just by using @code{dynamic-call} and
-@code{dynamic-args-call}. Instead, the usual way would be to write a
-special Guile<->X11 glue library that has intimate knowledge about both
-Guile and X11 and does whatever is necessary to make them inter-operate
-smoothly. This glue library could then be dynamically linked into a
-vanilla Guile interpreter and activated by calling its initialization
-function. That function would add all the new types and primitives to
-the Guile interpreter that it has to offer.
-
-From this setup the next logical step is to integrate these glue
-libraries into the module system of Guile so that you can load new
-primitives into a running system just as you can load new Scheme code.
-
-There is, however, another possibility to get a more thorough access to
-the functions contained in a dynamically linked library. Anthony Green
-has written @file{libffi}, a library that implements a @dfn{foreign
-function interface} for a number of different platforms. With it, you
-can extend the Spartan functionality of @code{dynamic-call} and
-@code{dynamic-args-call} considerably. There is glue code available in
-the Guile contrib archive to make @file{libffi} accessible from Guile.
-
-@node Compiled Code Modules
-@subsubsection Putting Compiled Code into Modules
-
-The new primitives that you add to Guile with
-@code{scm_c_define_gsubr} (@pxref{Primitive Procedures}) or with any
-of the other mechanisms are placed into the @code{(guile-user)} module
-by default. However, it is also possible to put new primitives into
-other modules.
-
-The mechanism for doing so is not very well thought out and is likely to
-change when the module system of Guile itself is revised, but it is
-simple and useful enough to document it as it stands.
-
-What @code{scm_c_define_gsubr} and the functions used by the snarfer
-really do is to add the new primitives to whatever module is the
-@emph{current module} when they are called. This is analogous to the
-way Scheme code is put into modules: the @code{define-module} expression
-at the top of a Scheme source file creates a new module and makes it the
-current module while the rest of the file is evaluated. The
-@code{define} expressions in that file then add their new definitions to
-this current module.
-
-Therefore, all we need to do is to make sure that the right module is
-current when calling @code{scm_c_define_gsubr} for our new primitives.
-
-@node Dynamic Linking and Compiled Code Modules
-@subsubsection Dynamic Linking and Compiled Code Modules
-
-The most interesting application of dynamically linked libraries is
-probably to use them for providing @emph{compiled code modules} to
-Scheme programs. As much fun as programming in Scheme is, every now and
-then comes the need to write some low-level C stuff to make Scheme even
-more fun.
-
-Not only can you put these new primitives into their own module (see the
-previous section), you can even put them into a shared library that is
-only then linked to your running Guile image when it is actually
-needed.
-
-An example will hopefully make everything clear. Suppose we want to
-make the Bessel functions of the C library available to Scheme in the
-module @samp{(math bessel)}. First we need to write the appropriate
-glue code to convert the arguments and return values of the functions
-from Scheme to C and back. Additionally, we need a function that will
-add them to the set of Guile primitives. Because this is just an
-example, we will only implement this for the @code{j0} function.
-
-@c FIXME::martin: Change all gh_ references to their scm_ equivalents.
-
-@smallexample
-#include <math.h>
-#include <libguile.h>
-
-SCM
-j0_wrapper (SCM x)
-@{
- return scm_double2num (j0 (scm_num2dbl (x, "j0")));
-@}
-
-void
-init_math_bessel ()
-@{
- scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
-@}
-@end smallexample
-
-We can already try to bring this into action by manually calling the low
-level functions for performing dynamic linking. The C source file needs
-to be compiled into a shared library. Here is how to do it on
-GNU/Linux, please refer to the @code{libtool} documentation for how to
-create dynamically linkable libraries portably.
-
-@smallexample
-gcc -shared -o libbessel.so -fPIC bessel.c
-@end smallexample
-
-Now fire up Guile:
-
-@smalllisp
-(define bessel-lib (dynamic-link "./libbessel.so"))
-(dynamic-call "init_math_bessel" bessel-lib)
-(j0 2)
-@result{} 0.223890779141236
-@end smalllisp
-
-The filename @file{./libbessel.so} should be pointing to the shared
-library produced with the @code{gcc} command above, of course. The
-second line of the Guile interaction will call the
-@code{init_math_bessel} function which in turn will register the C
-function @code{j0_wrapper} with the Guile interpreter under the name
-@code{j0}. This function becomes immediately available and we can call
-it from Scheme.
-
-Fun, isn't it? But we are only half way there. This is what
-@code{apropos} has to say about @code{j0}:
-
-@smallexample
-(apropos "j0")
-@print{} (guile-user): j0 #<primitive-procedure j0>
-@end smallexample
-
-As you can see, @code{j0} is contained in the root module, where all
-the other Guile primitives like @code{display}, etc live. In general,
-a primitive is put into whatever module is the @dfn{current module} at
-the time @code{scm_c_define_gsubr} is called.
-
-A compiled module should have a specially named @dfn{module init
-function}. Guile knows about this special name and will call that
-function automatically after having linked in the shared library. For
-our example, we replace @code{init_math_bessel} with the following code in
-@file{bessel.c}:
-
-@smallexample
-void
-init_math_bessel (void *unused)
-@{
- scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
- scm_c_export ("j0", NULL);
-@}
-
-void
-scm_init_math_bessel_module ()
-@{
- scm_c_define_module ("math bessel", init_math_bessel, NULL);
-@}
-@end smallexample
-
-The general pattern for the name of a module init function is:
-@samp{scm_init_}, followed by the name of the module where the
-individual hierarchical components are concatenated with underscores,
-followed by @samp{_module}.
-
-After @file{libbessel.so} has been rebuilt, we need to place the shared
-library into the right place.
-
-Once the module has been correctly installed, it should be possible to
-use it like this:
-
-@smallexample
-guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module")
-guile> (use-modules (math bessel))
-guile> (j0 2)
-0.223890779141236
-guile> (apropos "j0")
-@print{} (math bessel): j0 #<primitive-procedure j0>
-@end smallexample
+@node provide and require
+@subsection provide and require
-That's it!
+Aubrey Jaffer, mostly to support his portable Scheme library SLIB,
+implemented a provide/require mechanism for many Scheme implementations.
+Library files in SLIB @emph{provide} a feature, and when user programs
+@emph{require} that feature, the library file is loaded in.
-@deffn {Scheme Procedure} load-extension lib init
-@deffnx {C Function} scm_load_extension (lib, init)
-Load and initialize the extension designated by LIB and INIT.
-When there is no pre-registered function for LIB/INIT, this is
-equivalent to
+For example, the file @file{random.scm} in the SLIB package contains the
+line
@lisp
-(dynamic-call INIT (dynamic-link LIB))
+(provide 'random)
@end lisp
-When there is a pre-registered function, that function is called
-instead.
-
-Normally, there is no pre-registered function. This option exists
-only for situations where dynamic linking is unavailable or unwanted.
-In that case, you would statically link your program with the desired
-library, and register its init function right after Guile has been
-initialized.
-
-LIB should be a string denoting a shared library without any file type
-suffix such as ".so". The suffix is provided automatically. It
-should also not contain any directory components. Libraries that
-implement Guile Extensions should be put into the normal locations for
-shared libraries. We recommend to use the naming convention
-libguile-bla-blum for a extension related to a module `(bla blum)'.
-
-The normal way for a extension to be used is to write a small Scheme
-file that defines a module, and to load the extension into this
-module. When the module is auto-loaded, the extension is loaded as
-well. For example,
+so to use its procedures, a user would type
@lisp
-(define-module (bla blum))
-
-(load-extension "libguile-bla-blum" "bla_init_blum")
+(require 'random)
@end lisp
-@end deffn
-@node Variables
-@subsection Variables
-@tpindex Variables
+and they would magically become available, @emph{but still have the same
+names!} So this method is nice, but not as good as a full-featured
+module system.
-Each module has its own hash table, sometimes known as an @dfn{obarray},
-that maps the names defined in that module to their corresponding
-variable objects.
+When SLIB is used with Guile, provide and require can be used to access
+its facilities.
-A variable is a box-like object that can hold any Scheme value. It is
-said to be @dfn{undefined} if its box holds a special Scheme value that
-denotes undefined-ness (which is different from all other Scheme values,
-including for example @code{#f}); otherwise the variable is
-@dfn{defined}.
+@node Environments
+@subsection Environments
+@cindex environment
-On its own, a variable object is anonymous. A variable is said to be
-@dfn{bound} when it is associated with a name in some way, usually a
-symbol in a module obarray. When this happens, the relationship is
-mutual: the variable is bound to the name (in that module), and the name
-(in that module) is bound to the variable.
+Scheme, as defined in R5RS, does @emph{not} have a full module system.
+However it does define the concept of a top-level @dfn{environment}.
+Such an environment maps identifiers (symbols) to Scheme objects such
+as procedures and lists: @ref{About Closure}. In other words, it
+implements a set of @dfn{bindings}.
-(That's the theory, anyway. In practice, defined-ness and bound-ness
-sometimes get confused, because Lisp and Scheme implementations have
-often conflated --- or deliberately drawn no distinction between --- a
-name that is unbound and a name that is bound to a variable whose value
-is undefined. We will try to be clear about the difference and explain
-any confusion where it is unavoidable.)
+Environments in R5RS can be passed as the second argument to
+@code{eval} (@pxref{Fly Evaluation}). Three procedures are defined to
+return environments: @code{scheme-report-environment},
+@code{null-environment} and @code{interaction-environment} (@pxref{Fly
+Evaluation}).
-Variables do not have a read syntax. Most commonly they are created and
-bound implicitly by @code{define} expressions: a top-level @code{define}
-expression of the form
+In addition, in Guile any module can be used as an R5RS environment,
+i.e., passed as the second argument to @code{eval}.
+
+Note: the following two procedures are available only when the
+@code{(ice-9 r5rs)} module is loaded:
@lisp
-(define @var{name} @var{value})
+(use-modules (ice-9 r5rs))
@end lisp
-@noindent
-creates a variable with initial value @var{value} and binds it to the
-name @var{name} in the current module. But they can also be created
-dynamically by calling one of the constructor procedures
-@code{make-variable} and @code{make-undefined-variable}.
-
-First-class variables are especially useful for interacting with the
-current module system (@pxref{The Guile module system}).
-
-@deffn {Scheme Procedure} make-undefined-variable
-@deffnx {C Function} scm_make_undefined_variable ()
-Return a variable that is initially unbound.
-@end deffn
-
-@deffn {Scheme Procedure} make-variable init
-@deffnx {C Function} scm_make_variable (init)
-Return a variable initialized to value @var{init}.
-@end deffn
-
-@deffn {Scheme Procedure} variable-bound? var
-@deffnx {C Function} scm_variable_bound_p (var)
-Return @code{#t} iff @var{var} is bound to a value.
-Throws an error if @var{var} is not a variable object.
-@end deffn
+@deffn {Scheme Procedure} scheme-report-environment version
+@deffnx {Scheme Procedure} null-environment version
+@var{version} must be the exact integer `5', corresponding to revision
+5 of the Scheme report (the Revised^5 Report on Scheme).
+@code{scheme-report-environment} returns a specifier for an
+environment that is empty except for all bindings defined in the
+report that are either required or both optional and supported by the
+implementation. @code{null-environment} returns a specifier for an
+environment that is empty except for the (syntactic) bindings for all
+syntactic keywords defined in the report that are either required or
+both optional and supported by the implementation.
-@deffn {Scheme Procedure} variable-ref var
-@deffnx {C Function} scm_variable_ref (var)
-Dereference @var{var} and return its value.
-@var{var} must be a variable object; see @code{make-variable}
-and @code{make-undefined-variable}.
-@end deffn
+Currently Guile does not support values of @var{version} for other
+revisions of the report.
-@deffn {Scheme Procedure} variable-set! var val
-@deffnx {C Function} scm_variable_set_x (var, val)
-Set the value of the variable @var{var} to @var{val}.
-@var{var} must be a variable object, @var{val} can be any
-value. Return an unspecified value.
+The effect of assigning (through the use of @code{eval}) a variable
+bound in a @code{scheme-report-environment} (for example @code{car})
+is unspecified. Currently the environments specified by
+@code{scheme-report-environment} are not immutable in Guile.
@end deffn
-@deffn {Scheme Procedure} variable? obj
-@deffnx {C Function} scm_variable_p (obj)
-Return @code{#t} iff @var{obj} is a variable object, else
-return @code{#f}.
-@end deffn
@c Local Variables: