@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2010
+@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
* 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.
-* 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.
-* Accessing Modules from C:: How to work with modules with C code.
+* 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
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.
-
-A slightly different search mechanism is used when a client module
-specifies a version reference as part of a request to load a module
-(@pxref{R6RS Version References}). Instead of searching the directories
-in the load path for a single filename, Guile uses the elements of the
-version reference to locate matching, numbered subdirectories of a
-constructed base path. For example, a request for the
-@code{(rnrs base)} module with version reference @code{(6)} would cause
-Guile to discover the @code{rnrs/6} subdirectory (if it exists in any of
-the directories in the load path) and search its contents for the
-filename @code{base.scm}.
-
-When multiple modules are found that match a version reference, Guile
-sorts these modules by version number, followed by the length of their
-version specifications, in order to choose a ``best'' match.
-
-@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}).
+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
@subsection Using Guile Modules
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 @code{%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
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
#: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)
+ #: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
subsequently accessed by the current module. The mapping of old to new
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
@cindex binding renamer
@lisp
- (MODULE-NAME [:select SELECTION] [:renamer RENAMER])
+ (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.
-
-In addition to the above, @var{spec} can also include a @code{:version}
+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
+ #:version VERSION-SPEC
@end lisp
-where @var{version-spec} is an R6RS-compatible version reference. The
-presence of this clause changes Guile's search behavior as described in
-the section on module name resolution
-(@pxref{General Information about Modules}). 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}.
+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.
-Signal error if module name is not resolvable.
-@end deffn
-
-
-@c FIXME::martin: Is this correct, and is there more to say?
-@c FIXME::martin: Define term and concept `syntax transformer' somewhere.
-
-@deffn syntax use-syntax module-name
-Load the module @code{module-name} and use its syntax
-transformer as the syntax transformer for the currently defined module,
-as well as installing it as the current syntax transformer.
+If the module name is not resolvable, @code{use-modules} will signal an
+error.
@end deffn
@deffn syntax @@ module-name binding-name
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.
@lisp
(define-module (ice-9 popen))
@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
-or pairs of symbols. This is equivalent to @code{(export @var{list})}
+or pairs of symbols. This is equivalent to @code{(export @var{list})}
in the module body.
@item #:re-export @var{list}
imported by the current module from other modules. This is equivalent
to @code{re-export} below.
-@item #:export-syntax @var{list}
-@cindex export-syntax
-Export all identifiers in @var{list} which must be a list of symbols
-or pairs of symbols. The identifiers in @var{list} must refer to
-macros (@pxref{Macros}) defined in the current module. This is
-equivalent to @code{(export-syntax @var{list})} in the module body.
-
-@item #:re-export-syntax @var{list}
-@cindex re-export-syntax
-Re-export all identifiers in @var{list} which must be a list of
-symbols or pairs of symbols. The symbols in @var{list} must refer to
-macros imported by the current module from other modules. This is
-equivalent to @code{(re-export-syntax @var{list})} in the module body.
-
@item #:replace @var{list}
@cindex replace
@cindex replacing binding
replacement results in an ``override'' warning message,
@code{#:replace} avoids that.
-This is useful for modules that export bindings that have the same
-name as core bindings. @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.
-
-For instance, SRFI-39 exports a binding named
-@code{current-input-port} (@pxref{SRFI-39}) that is a function which
-is upwardly compatible with the core @code{current-input-port}
-function. Therefore, SRFI-39 exports its version with
-@code{#:replace}.
-
-SRFI-19, on the other hand, 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}). Therefore,
-SRFI-19 does not use @code{#:replace}.
-
-The @code{#: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 @code{<=} is an inference
-instead of a comparison.
+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.
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
(replace warn-override-core warn last)
@end lisp
-@item #:no-backtrace
-@cindex no backtrace
-Tell Guile not to record information for procedure backtraces when
-executing the procedures in this module.
-
@item #:pure
@cindex pure module
Create a @dfn{pure} module, that is a module which does not contain any
@end table
@end deffn
-@c end
@deffn syntax export variable @dots{}
Add all @var{variable}s (which must be symbols or pairs of symbols) to
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
@deffn syntax re-export variable @dots{}
Add all @var{variable}s (which must be symbols or pairs of symbols) to
imported by the current module from some other module.
@end deffn
-@node Module System Reflection
-@subsection Module System Reflection
-
-The previous sections have described a declarative view of the module
-system. You can also work with it programmatically by accessing and
-modifying various parts of the Scheme objects that Guile uses to
-implement the module system.
-
-At any time, there is a @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.
-
-These module objects can be used as the second argument to @code{eval}.
-
-@deffn {Scheme Procedure} current-module
-Return the current module object.
-@end deffn
-
-@deffn {Scheme Procedure} set-current-module module
-Set the current module to @var{module} and return
-the previous current module.
-@end deffn
-
-@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}).
-
-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
-
-@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
-
-@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.
+@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
-@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
-
-
-@node Included Guile Modules
-@subsection Included Guile Modules
-
-@c FIXME::martin: Review me!
-
-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.
-
-@item (ice-9 debug)
-Mikael Djurfeldt's source-level debugging support for Guile
-(@pxref{Tracing}).
-
-@item (ice-9 expect)
-Actions based on matching input from a port (@pxref{Expect}).
-
-@item (ice-9 format)
-Formatted output in the style of Common Lisp (@pxref{Formatted
-Output}).
-
-@item (ice-9 ftw)
-File tree walker (@pxref{File Tree Walk}).
-
-@item (ice-9 getopt-long)
-Command line option processing (@pxref{getopt-long}).
-
-@item (ice-9 history)
-Refer to previous interactive expressions (@pxref{Value History}).
-
-@item (ice-9 popen)
-Pipes to and from child processes (@pxref{Pipes}).
-
-@item (ice-9 pretty-print)
-Nicely formatted output of Scheme expressions and objects
-(@pxref{Pretty Printing}).
+@node Modules and the File System
+@subsection Modules and the File System
-@item (ice-9 q)
-First-in first-out queues (@pxref{Queues}).
+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.
-@item (ice-9 rdelim)
-Line- and character-delimited input (@pxref{Line/Delimited}).
+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}.
-@item (ice-9 readline)
-@code{readline} interactive command line editing (@pxref{Readline
-Support}).
+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}.
-@item (ice-9 receive)
-Multiple-value handling with @code{receive} (@pxref{Multiple Values}).
+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.
-@item (ice-9 regex)
-Regular expression matching (@pxref{Regular Expressions}).
+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.
-@item (ice-9 rw)
-Block string input/output (@pxref{Block Reading and Writing}).
-
-@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}).
-
-@item (ice-9 threads)
-Guile's support for multi threaded execution (@pxref{Scheduling}).
-
-@item (ice-9 documentation)
-Online documentation (REFFIXME).
-
-@item (srfi srfi-1)
-A library providing a lot of useful list and pair processing
-procedures (@pxref{SRFI-1}).
-
-@item (srfi srfi-2)
-Support for @code{and-let*} (@pxref{SRFI-2}).
-
-@item (srfi srfi-4)
-Support for homogeneous numeric vectors (@pxref{SRFI-4}).
-
-@item (srfi srfi-6)
-Support for some additional string port procedures (@pxref{SRFI-6}).
-
-@item (srfi srfi-8)
-Multiple-value handling with @code{receive} (@pxref{SRFI-8}).
-
-@item (srfi srfi-9)
-Record definition with @code{define-record-type} (@pxref{SRFI-9}).
-
-@item (srfi srfi-10)
-Read hash extension @code{#,()} (@pxref{SRFI-10}).
-
-@item (srfi srfi-11)
-Multiple-value handling with @code{let-values} and @code{let*-values}
-(@pxref{SRFI-11}).
-
-@item (srfi srfi-13)
-String library (@pxref{SRFI-13}).
-
-@item (srfi srfi-14)
-Character-set library (@pxref{SRFI-14}).
-
-@item (srfi srfi-16)
-@code{case-lambda} procedures of variable arity (@pxref{SRFI-16}).
-
-@item (srfi srfi-17)
-Getter-with-setter support (@pxref{SRFI-17}).
-
-@item (srfi srfi-19)
-Time/Date library (@pxref{SRFI-19}).
-
-@item (srfi srfi-26)
-Convenient syntax for partial application (@pxref{SRFI-26})
-
-@item (srfi srfi-31)
-@code{rec} convenient recursive expressions (@pxref{SRFI-31})
-
-@item (ice-9 slib)
-This module contains hooks for using Aubrey Jaffer's portable Scheme
-library SLIB from Guile (@pxref{SLIB}).
-@end table
+For more information on where and how to install Scheme modules,
+@xref{Installing Site Packages}.
@node R6RS Version References
@end lisp
-@node Accessing Modules from C
-@subsection Accessing Modules from C
+@node R6RS Libraries
+@subsection R6RS Libraries
-The last sections have described how modules are used in Scheme code,
-which is the recommended way of creating and accessing modules. You
-can also work with modules from C, but it is more cumbersome.
+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:
-The following procedures are available.
+@lisp
+ (library (mylib (1 2))
+ (export mybinding)
+ (import (otherlib (3))))
+@end lisp
-@deftypefn {C Procedure} SCM scm_current_module ()
-Return the module that is the @emph{current module}.
-@end deftypefn
+is equivalent to the module definition:
-@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
+@lisp
+ (define-module (mylib)
+ #:version (1 2)
+ #:use-module ((otherlib) #:version (3))
+ #:export (mybinding))
+@end lisp
-@deftypefn {C Procedure} 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
+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:
-@deftypefn {C Procedure} 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
+@lisp
+ run
+ expand
+ (meta @var{level})
+@end lisp
-@deftypefn {C Procedure} SCM scm_lookup (SCM @var{name})
-Like @code{scm_c_lookup}, but the symbol is specified directly.
-@end deftypefn
+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.
-@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})
-Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified
-module is used instead of the current one.
-@end deftypefn
+Import sets in turn take one of the following forms:
-@deftypefn {C Procedure} 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
+@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
-@deftypefn {C Procedure} SCM scm_define (SCM @var{name}, SCM @var{val})
-Like @code{scm_c_define}, but the symbol is specified directly.
-@end deftypefn
+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:
-@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})
-Like @code{scm_c_define} and @code{scm_define}, but the specified
-module is used instead of the current one.
-@end deftypefn
+@itemize @bullet
-@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}.
-@end deftypefn
+@item
+The @code{library} sub-form is used to specify libraries for import
+whose names begin with the identifier ``library.''
-@deftypefn {C Procedure} 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.
+@item
+The @code{only} sub-form imports only the specified @var{identifier}s
+from the given @var{import-set}.
-The parameter @var{name} is a string with the symbols that make up
-the module name, separated by spaces. For example, @samp{"foo bar"} names
-the module @samp{(foo bar)}.
+@item
+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.
-When there already exists a module named @var{name}, it is used
-unchanged, otherwise, an empty module is created.
-@end deftypefn
+@item
+The @code{prefix} sub-form imports all of the bindings exported
+by @var{import-set}, first prefixing them with the specified
+@var{identifier}.
-@deftypefn {C Procedure} 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
+@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}.
-@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
+@end itemize
-@deftypefn {C Procedure} 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
+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.
-@deftypefn {C Procedure} SCM 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
+@end deffn
+
+@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
@node Variables
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.
+symbol in a module obarray. When this happens, the name is said to be
+bound to the variable, in that module.
(That's the theory, anyway. In practice, defined-ness and bound-ness
sometimes get confused, because Lisp and Scheme implementations have
@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.
+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
@deffn {Scheme Procedure} variable-ref var
value. Return an unspecified value.
@end deffn
+@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
+
@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}.
+Return @code{#t} if @var{obj} is a variable object, else return
+@code{#f}.
+@end deffn
+
+
+@node Module System Reflection
+@subsection Module System Reflection
+
+The previous sections have described a declarative view of the module
+system. You can also work with it programmatically by accessing and
+modifying various parts of the Scheme objects that Guile uses to
+implement the module system.
+
+At any time, there is a @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.
+
+These module objects can be used as the second argument to @code{eval}.
+
+@deffn {Scheme Procedure} current-module
+@deffnx {C Function} scm_current_module ()
+Return the current module object.
+@end deffn
+
+@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
+
+@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}).
+
+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
+
+@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
+
+@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
+
+@deffn {Scheme Procedure} module-uses module
+Return a list of the interfaces used by @var{module}.
+@end deffn
+
+@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
+
+@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}.
+
+@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
+@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
+
+@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
+
+@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
+
+@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
+
+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
+@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
+can also work with modules from C, but it is more cumbersome.
+
+The following procedures are available.
+
+@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 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 Function} SCM scm_lookup (SCM @var{name})
+Like @code{scm_c_lookup}, but the symbol is specified directly.
+@end deftypefn
+
+@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 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 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 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
+
+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 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.
+
+The parameter @var{name} is a string with the symbols that make up
+the module name, separated by spaces. For example, @samp{"foo bar"} names
+the module @samp{(foo bar)}.
+
+When there already exists a module named @var{name}, it is used
+unchanged, otherwise, an empty module is created.
+@end deftypefn
+
+@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 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 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 provide and require
@subsection provide and require
HCoop / bpt / guile.git / blobdiff