[Guile-commits] GNU Guile branch, stable-2.0, updated. v2.0.3-107-g992a387

[Andy Wingo]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".

http://git.savannah.gnu.org/cgit/guile.git/commit/?id=992a387958946a8726583567ff630760e50bf7b3

The branch, stable-2.0 has been updated
       via  992a387958946a8726583567ff630760e50bf7b3 (commit)
      from  449bf60b819afed8063e45dfbb9ea61280ae518f (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 992a387958946a8726583567ff630760e50bf7b3
Author: Andy Wingo <address@hidden>
Date:   Sat Jan 7 00:45:44 2012 +0100

    update api-modules.texi
    
    * doc/ref/api-modules.texi (Modules): Add subsection for "Modules and
      the File System".  Move "Included Guile Modules" to the end.  Move
      "Module System Reflection" after "Variables", as we need to know about
      variables.  Flesh out "Module System Reflection" a bit, with docs on
      module-ref, module-variable, and other bindings.  General editing.

-----------------------------------------------------------------------

Summary of changes:
 doc/ref/api-modules.texi |  716 +++++++++++++++++++++++-----------------------
 1 files changed, 362 insertions(+), 354 deletions(-)

diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi
index 33c9819..9830cfd 100644
--- a/doc/ref/api-modules.texi
+++ b/doc/ref/api-modules.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 
2008, 2009, 2010, 2011
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 
2008, 2009, 2010, 2011, 2012
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -44,12 +44,13 @@ be used for interacting with the module system.
 * 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.
 * R6RS Libraries::              The library and import forms.
-* Accessing Modules from C::    How to work with modules with C code.
 * Variables::                   First-class variables.
+* Module System Reflection::    First-class modules.
+* Accessing Modules from C::    How to work with modules with C code.
+* Included Guile Modules::      Which modules come with Guile?
 * provide and require::         The SLIB feature mechanism.
 * Environments::                R5RS top-level environments.
 @end menu
@@ -61,12 +62,6 @@ 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
@@ -81,42 +76,18 @@ algorithmically @dfn{rename} bindings.  In contrast, when 
using the
 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
address@hidden (@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 
address@hidden(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.
-
address@hidden 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
address@hidden 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
address@hidden(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
address@hidden(ice-9 popen)}, Guile first looks to see if it has loaded
address@hidden(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
@@ -198,14 +169,11 @@ has not yet been loaded yet will be loaded when 
referenced by a
 You can also use the @code{@@} and @code{@@@@} syntaxes as the target
 of a @code{set!} when the binding refers to a variable.
 
address@hidden 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}.
address@hidden Insert gratuitous C++ slam here.  --ttn
 @end deffn
 
address@hidden 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
@@ -218,7 +186,7 @@ whose public interface is found and used.
 
 @cindex binding renamer
 @lisp
- (MODULE-NAME [:select SELECTION] [:renamer RENAMER])
+ (MODULE-NAME [#:select SELECTION] [#:renamer RENAMER])
 @end lisp
 
 in which case a custom interface is newly created and used.
@@ -229,37 +197,26 @@ 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}
+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} 
+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}.
-
-Signal error if module name is not resolvable.
address@hidden deffn
-
-
address@hidden FIXME::martin: Is this correct, and is there more to say?
address@hidden FIXME::martin: Define term and concept `syntax 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.
 
address@hidden 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
@@ -293,10 +250,8 @@ Export all bindings which should be in the public 
interface, either
 by using @code{define-public} or @code{export} (both documented below).
 @end itemize
 
address@hidden begin (scm-doc-string "boot-9.scm" "define-module")
 @deffn syntax define-module module-name [options @dots{}]
address@hidden is of the form @code{(hierarchy file)}.  One
-example of this is
address@hidden is a list of one or more symbols.
 
 @lisp
 (define-module (ice-9 popen))
@@ -309,17 +264,11 @@ The @var{options} are keyword/value pairs which specify 
more about the
 defined module.  The recognized options and their meaning is shown in
 the following table.
 
address@hidden 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}).
 
address@hidden #: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
@@ -347,7 +296,7 @@ the module is used.
 @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}
@@ -357,20 +306,6 @@ 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.
 
address@hidden #:export-syntax @var{list}
address@hidden 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.
-
address@hidden #:re-export-syntax @var{list}
address@hidden 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
@@ -400,6 +335,9 @@ 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.
 
@@ -464,6 +402,10 @@ 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
@@ -472,11 +414,6 @@ The default duplicate binding resolution policy is given 
by the
 (replace warn-override-core warn last)
 @end lisp
 
address@hidden #:no-backtrace
address@hidden 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
@@ -486,7 +423,6 @@ do not know anything about dangerous procedures.
 @end table
 
 @end deffn
address@hidden end
 
 @deffn syntax export variable @dots{}
 Add all @var{variable}s (which must be symbols or pairs of symbols) to 
@@ -496,11 +432,9 @@ current module and its @code{cdr} specifies a name for the 
binding in
 the current module's public interface.
 @end deffn
 
address@hidden begin (scm-doc-string "boot-9.scm" "define-public")
 @deffn syntax define-public @dots{}
 Equivalent to @code{(begin (define foo ...) (export foo))}.
 @end deffn
address@hidden end
 
 @deffn syntax re-export variable @dots{}
 Add all @var{variable}s (which must be symbols or pairs of symbols) to 
@@ -509,184 +443,47 @@ symbols are handled as in @code{export}.  Re-exported 
bindings must be
 imported by the current module from some other module.
 @end deffn
 
address@hidden Module System Reflection
address@hidden 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}.
-
address@hidden {Scheme Procedure} current-module
-Return the current module object.
address@hidden deffn
-
address@hidden {Scheme Procedure} set-current-module module
-Set the current module to @var{module} and return
-the previous current module.
address@hidden deffn
-
address@hidden {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
address@hidden's dynamic extent is re-entered, then the current module is
-saved, and the previously saved inner module is set current again.
address@hidden deffn
-
address@hidden {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.
address@hidden deffn
-
address@hidden {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.
address@hidden 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
address@hidden:replace} above.
 @end deffn
 
address@hidden {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}.
address@hidden deffn
-
address@hidden {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.
address@hidden deffn
-
-
address@hidden Included Guile Modules
address@hidden Included Guile Modules
-
address@hidden 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:
-
address@hidden @strong
address@hidden boot-9
-boot-9 is Guile's initialization module, and it is always loaded when
-Guile starts up.
-
address@hidden (ice-9 expect)
-Actions based on matching input from a port (@pxref{Expect}).
-
address@hidden (ice-9 format)
-Formatted output in the style of Common Lisp (@pxref{Formatted
-Output}).
-
address@hidden (ice-9 ftw)
-File tree walker (@pxref{File Tree Walk}).
-
address@hidden (ice-9 getopt-long)
-Command line option processing (@pxref{getopt-long}).
-
address@hidden (ice-9 history)
-Refer to previous interactive expressions (@pxref{Value History}).
-
address@hidden (ice-9 popen)
-Pipes to and from child processes (@pxref{Pipes}).
-
address@hidden (ice-9 pretty-print)
-Nicely formatted output of Scheme expressions and objects
-(@pxref{Pretty Printing}).
-
address@hidden (ice-9 q)
-First-in first-out queues (@pxref{Queues}).
-
address@hidden (ice-9 rdelim)
-Line- and character-delimited input (@pxref{Line/Delimited}).
-
address@hidden (ice-9 readline)
address@hidden interactive command line editing (@pxref{Readline
-Support}).
-
address@hidden (ice-9 receive)
-Multiple-value handling with @code{receive} (@pxref{Multiple Values}).
-
address@hidden (ice-9 regex)
-Regular expression matching (@pxref{Regular Expressions}).
-
address@hidden (ice-9 rw)
-Block string input/output (@pxref{Block Reading and Writing}).
-
address@hidden (ice-9 streams)
-Sequence of values calculated on-demand (@pxref{Streams}).
-
address@hidden (ice-9 syncase)
-R5RS @code{syntax-rules} macro system (@pxref{Syntax Rules}).
-
address@hidden (ice-9 threads)
-Guile's support for multi threaded execution (@pxref{Scheduling}).
-
address@hidden (ice-9 documentation)
-Online documentation (REFFIXME).
-
address@hidden (srfi srfi-1)
-A library providing a lot of useful list and pair processing
-procedures (@pxref{SRFI-1}).
-
address@hidden (srfi srfi-2)
-Support for @code{and-let*} (@pxref{SRFI-2}).
-
address@hidden (srfi srfi-4)
-Support for homogeneous numeric vectors (@pxref{SRFI-4}).
-
address@hidden (srfi srfi-6)
-Support for some additional string port procedures (@pxref{SRFI-6}).
-
address@hidden (srfi srfi-8)
-Multiple-value handling with @code{receive} (@pxref{SRFI-8}).
-
address@hidden (srfi srfi-9)
-Record definition with @code{define-record-type} (@pxref{SRFI-9}).
-
address@hidden (srfi srfi-10)
-Read hash extension @code{#,()} (@pxref{SRFI-10}).
-
address@hidden (srfi srfi-11)
-Multiple-value handling with @code{let-values} and @code{let*-values}
-(@pxref{SRFI-11}).
-
address@hidden (srfi srfi-13)
-String library (@pxref{SRFI-13}).
-
address@hidden (srfi srfi-14)
-Character-set library (@pxref{SRFI-14}).
address@hidden Modules and the File System
address@hidden Modules and the File System
 
address@hidden (srfi srfi-16)
address@hidden procedures of variable arity (@pxref{SRFI-16}).
+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.
 
address@hidden (srfi srfi-17)
-Getter-with-setter support (@pxref{SRFI-17}).
+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}.
 
address@hidden (srfi srfi-19)
-Time/Date library (@pxref{SRFI-19}).
+In this case, loading @code{(ice-9 popen)} will eventually cause Guile
+to run @code{(primitive-load-path "ice-9/popen")}.
address@hidden will search for a file @file{ice-9/popen} in
+the @code{%load-path} (@pxref{Build Config}).  For each directory in
address@hidden, 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
address@hidden/popen}.  @xref{Loading}, for more on
address@hidden
 
address@hidden (srfi srfi-26)
-Convenient syntax for partial application (@pxref{SRFI-26})
+If a corresponding compiled @file{.go} file is found in the
address@hidden 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.
 
address@hidden (srfi srfi-31)
address@hidden convenient recursive expressions (@pxref{SRFI-31})
+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.
 
address@hidden (ice-9 slib)
-This module contains hooks for using Aubrey Jaffer's portable Scheme
-library SLIB from Guile (@pxref{SLIB}).
address@hidden table
+For more information on where and how to install Scheme modules,
address@hidden Site Packages}.
 
 
 @node R6RS Version References
@@ -910,6 +707,196 @@ same form as in the @code{library} form described above.
 @end deffn
 
 
address@hidden Variables
address@hidden Variables
address@hidden Variables
+
+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.
+
+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
address@hidden
+
+On its own, a variable object is anonymous.  A variable is said to be
address@hidden 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.
+
+(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.)
+
+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
+
address@hidden
+(define @var{name} @var{value})
address@hidden lisp
+
address@hidden
+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
address@hidden and @code{make-undefined-variable}.
+
address@hidden {Scheme Procedure} make-undefined-variable
address@hidden {C Function} scm_make_undefined_variable ()
+Return a variable that is initially unbound.
address@hidden deffn
+
address@hidden {Scheme Procedure} make-variable init
address@hidden {C Function} scm_make_variable (init)
+Return a variable initialized to value @var{init}.
address@hidden deffn
+
address@hidden {Scheme Procedure} variable-bound? var
address@hidden {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.
address@hidden deffn
+
address@hidden {Scheme Procedure} variable-ref var
address@hidden {C Function} scm_variable_ref (var)
+Dereference @var{var} and return its value.
address@hidden must be a variable object; see @code{make-variable}
+and @code{make-undefined-variable}.
address@hidden deffn
+
address@hidden {Scheme Procedure} variable-set! var val
address@hidden {C Function} scm_variable_set_x (var, val)
+Set the value of the variable @var{var} to @var{val}.
address@hidden must be a variable object, @var{val} can be any
+value. Return an unspecified value.
address@hidden deffn
+
address@hidden {Scheme Procedure} variable-unset! var
address@hidden {C Function} scm_variable_unset_x (var)
+Unset the value of the variable @var{var}, leaving @var{var} unbound.
address@hidden deffn
+
address@hidden {Scheme Procedure} variable? obj
address@hidden {C Function} scm_variable_p (obj)
+Return @code{#t} iff @var{obj} is a variable object, else
+return @code{#f}.
address@hidden deffn
+
+
address@hidden Module System Reflection
address@hidden 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}.
+
address@hidden {Scheme Procedure} current-module
address@hidden {C Function} scm_current_module ()
+Return the current module object.
address@hidden deffn
+
address@hidden {Scheme Procedure} set-current-module module
address@hidden {C Function} scm_set_current_module (module)
+Set the current module to @var{module} and return
+the previous current module.
address@hidden deffn
+
address@hidden {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
address@hidden's dynamic extent is re-entered, then the current module is
+saved, and the previously saved inner module is set current again.
address@hidden deffn
+
address@hidden {Scheme Procedure} resolve-module name [autoload=#t] 
[version=#f] [#:ensure=#t]
address@hidden {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.
address@hidden deffn
+
address@hidden {Scheme Procedure} resolve-interface name [#:select=#f] 
[#:hide='()] [#:select=()] [#:prefix=#f] [#:renamer] [#: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.
address@hidden deffn
+
address@hidden {Scheme Procedure} module-uses module
+Return a list of the interfaces used by @var{module}.
address@hidden deffn
+
address@hidden {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}.
address@hidden deffn
+
address@hidden {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.
address@hidden 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}.
+
address@hidden {Scheme Procedure} module-variable module name
+Return the variable bound to @var{name} (a symbol) in @var{module}, or
address@hidden if @var{name} is unbound.
address@hidden deffn
+
address@hidden {Scheme Procedure} module-add! module name var
+Define a new binding between @var{name} (a symbol) and @var{var} (a
+variable) in @var{module}.
address@hidden deffn
+
address@hidden {Scheme Procedure} module-ref module name
+Look up the value bound to @var{name} in @var{module}.  Like
address@hidden, but also does a @code{variable-ref} on the
+resulting variable, raising an error if @var{name} is unbound.
address@hidden deffn
+
address@hidden {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
address@hidden
address@hidden deffn
+
address@hidden {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}.
address@hidden 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
 
@@ -919,15 +906,6 @@ can also work with modules from C, but it is more 
cumbersome.
 
 The following procedures are available.
 
address@hidden {C Function} SCM scm_current_module ()
-Return the module that is the @emph{current module}.
address@hidden deftypefn
-
address@hidden {C Function} SCM scm_set_current_module (SCM @var{module})
-Set the current module to @var{module} and return the previous current
-module.
address@hidden deftypefn
-
 @deftypefn {C Function} SCM scm_c_call_with_current_module (SCM @var{module}, 
SCM (address@hidden)(void *), void address@hidden)
 Call @var{func} and make @var{module} the current module during the
 call.  The argument @var{data} is passed to @var{func}.  The return
@@ -1053,11 +1031,6 @@ that way either, create an empty module.  The name is 
interpreted as
 for @code{scm_c_define_module}.
 @end deftypefn
 
address@hidden {C Function} SCM scm_resolve_module (SCM @var{name})
-Like @code{scm_c_resolve_module}, but the name is given as a real list
-of symbols.
address@hidden deftypefn
-
 @deftypefn {C Function} SCM scm_c_use_module ({const char address@hidden)
 Add the module named @var{name} to the uses list of the current
 module, as with @code{(use-modules @var{name})}.  The name is
@@ -1071,87 +1044,122 @@ of the current module.  The list of names is 
terminated by
 @end deftypefn
 
 
address@hidden Variables
address@hidden Variables
address@hidden Variables
address@hidden Included Guile Modules
address@hidden Included Guile Modules
 
-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.
+Some modules are included in the Guile distribution; here are references
+to the entries in this manual which describe them in more detail:
 
-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
address@hidden
address@hidden @strong
address@hidden boot-9
+boot-9 is Guile's initialization module, and it is always loaded when
+Guile starts up.
 
-On its own, a variable object is anonymous.  A variable is said to be
address@hidden 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.
address@hidden (ice-9 expect)
+Actions based on matching input from a port (@pxref{Expect}).
 
-(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.)
address@hidden (ice-9 format)
+Formatted output in the style of Common Lisp (@pxref{Formatted
+Output}).
 
-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
address@hidden (ice-9 ftw)
+File tree walker (@pxref{File Tree Walk}).
 
address@hidden
-(define @var{name} @var{value})
address@hidden lisp
address@hidden (ice-9 getopt-long)
+Command line option processing (@pxref{getopt-long}).
 
address@hidden
-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
address@hidden and @code{make-undefined-variable}.
address@hidden (ice-9 history)
+Refer to previous interactive expressions (@pxref{Value History}).
 
address@hidden {Scheme Procedure} make-undefined-variable
address@hidden {C Function} scm_make_undefined_variable ()
-Return a variable that is initially unbound.
address@hidden deffn
address@hidden (ice-9 popen)
+Pipes to and from child processes (@pxref{Pipes}).
 
address@hidden {Scheme Procedure} make-variable init
address@hidden {C Function} scm_make_variable (init)
-Return a variable initialized to value @var{init}.
address@hidden deffn
address@hidden (ice-9 pretty-print)
+Nicely formatted output of Scheme expressions and objects
+(@pxref{Pretty Printing}).
 
address@hidden {Scheme Procedure} variable-bound? var
address@hidden {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.
address@hidden deffn
address@hidden (ice-9 q)
+First-in first-out queues (@pxref{Queues}).
 
address@hidden {Scheme Procedure} variable-ref var
address@hidden {C Function} scm_variable_ref (var)
-Dereference @var{var} and return its value.
address@hidden must be a variable object; see @code{make-variable}
-and @code{make-undefined-variable}.
address@hidden deffn
address@hidden (ice-9 rdelim)
+Line- and character-delimited input (@pxref{Line/Delimited}).
 
address@hidden {Scheme Procedure} variable-set! var val
address@hidden {C Function} scm_variable_set_x (var, val)
-Set the value of the variable @var{var} to @var{val}.
address@hidden must be a variable object, @var{val} can be any
-value. Return an unspecified value.
address@hidden deffn
address@hidden (ice-9 readline)
address@hidden interactive command line editing (@pxref{Readline
+Support}).
 
address@hidden {Scheme Procedure} variable-unset! var
address@hidden {C Function} scm_variable_unset_x (var)
-Unset the value of the variable @var{var}, leaving @var{var} unbound.
address@hidden deffn
address@hidden (ice-9 receive)
+Multiple-value handling with @code{receive} (@pxref{Multiple Values}).
 
address@hidden {Scheme Procedure} variable? obj
address@hidden {C Function} scm_variable_p (obj)
-Return @code{#t} iff @var{obj} is a variable object, else
-return @code{#f}.
address@hidden deffn
address@hidden (ice-9 regex)
+Regular expression matching (@pxref{Regular Expressions}).
+
address@hidden (ice-9 rw)
+Block string input/output (@pxref{Block Reading and Writing}).
+
address@hidden (ice-9 streams)
+Sequence of values calculated on-demand (@pxref{Streams}).
+
address@hidden (ice-9 syncase)
+R5RS @code{syntax-rules} macro system (@pxref{Syntax Rules}).
+
address@hidden (ice-9 threads)
+Guile's support for multi threaded execution (@pxref{Scheduling}).
+
address@hidden (ice-9 documentation)
+Online documentation (REFFIXME).
+
address@hidden (srfi srfi-1)
+A library providing a lot of useful list and pair processing
+procedures (@pxref{SRFI-1}).
+
address@hidden (srfi srfi-2)
+Support for @code{and-let*} (@pxref{SRFI-2}).
+
address@hidden (srfi srfi-4)
+Support for homogeneous numeric vectors (@pxref{SRFI-4}).
+
address@hidden (srfi srfi-6)
+Support for some additional string port procedures (@pxref{SRFI-6}).
+
address@hidden (srfi srfi-8)
+Multiple-value handling with @code{receive} (@pxref{SRFI-8}).
+
address@hidden (srfi srfi-9)
+Record definition with @code{define-record-type} (@pxref{SRFI-9}).
+
address@hidden (srfi srfi-10)
+Read hash extension @code{#,()} (@pxref{SRFI-10}).
+
address@hidden (srfi srfi-11)
+Multiple-value handling with @code{let-values} and @code{let*-values}
+(@pxref{SRFI-11}).
+
address@hidden (srfi srfi-13)
+String library (@pxref{SRFI-13}).
+
address@hidden (srfi srfi-14)
+Character-set library (@pxref{SRFI-14}).
+
address@hidden (srfi srfi-16)
address@hidden procedures of variable arity (@pxref{SRFI-16}).
+
address@hidden (srfi srfi-17)
+Getter-with-setter support (@pxref{SRFI-17}).
+
address@hidden (srfi srfi-19)
+Time/Date library (@pxref{SRFI-19}).
+
address@hidden (srfi srfi-26)
+Convenient syntax for partial application (@pxref{SRFI-26})
+
address@hidden (srfi srfi-31)
address@hidden convenient recursive expressions (@pxref{SRFI-31})
+
address@hidden (ice-9 slib)
+This module contains hooks for using Aubrey Jaffer's portable Scheme
+library SLIB from Guile (@pxref{SLIB}).
address@hidden table
 
 
 @node provide and require


hooks/post-receive
-- 
GNU Guile