summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ref/ChangeLog6
-rw-r--r--doc/ref/scheme-evaluation.texi2
-rw-r--r--doc/ref/scheme-modules.texi104
3 files changed, 85 insertions, 27 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index 8b8ff5a6b..88d4c02d8 100644
--- a/doc/ref/ChangeLog
+++ b/doc/ref/ChangeLog
@@ -1,3 +1,9 @@
+2002-08-02 Gary Houston <ghouston@arglist.com>
+
+ * scheme-modules.texi: split "Scheme and modules" into
+ "provide and require" and "Environments". Mention R5RS
+ environments.
+
2002-07-16 Neil Jerram <neil@ossau.uklinux.net>
* scheme-options.texi (Debugger options): New subsection
diff --git a/doc/ref/scheme-evaluation.texi b/doc/ref/scheme-evaluation.texi
index fbfcd87a8..b73f8316d 100644
--- a/doc/ref/scheme-evaluation.texi
+++ b/doc/ref/scheme-evaluation.texi
@@ -182,6 +182,8 @@ this procedure directly, use the procedures @code{read-enable},
@node Fly Evaluation
@section Procedures for On the Fly Evaluation
+@xref{Environments}.
+
@rnindex eval
@c ARGFIXME environment/environment specifier
@deffn {Scheme Procedure} eval exp module
diff --git a/doc/ref/scheme-modules.texi b/doc/ref/scheme-modules.texi
index 9e3ddf894..c9279258c 100644
--- a/doc/ref/scheme-modules.texi
+++ b/doc/ref/scheme-modules.texi
@@ -36,17 +36,15 @@ In addition, Guile offers variables as first-class objects. They can
be used for interacting with the module system.
@menu
-* Scheme and modules:: How modules are handled in standard Scheme.
+* 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 Scheme and modules
-@section Scheme and modules
-
-Scheme, as defined in R5RS, does @emph{not} have a module system at all.
+@node provide and require
+@section provide and require
Aubrey Jaffer, mostly to support his portable Scheme library SLIB,
implemented a provide/require mechanism for many Scheme implementations.
@@ -70,10 +68,56 @@ 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
+@section 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}.
+
+@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
@section 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.
@@ -101,10 +145,17 @@ there is still some flux.
@node General Information about Modules
@subsection General Information about Modules
-A Guile module is a collection of named procedures, variables and
-macros, altogether called the @dfn{bindings}, since they bind, or
-associate, a symbol (the name) to a Scheme object (procedure, variable,
-or macro). Within a module, all bindings are visible. Certain bindings
+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.
+Environment in which a lambda is excuted 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
called the module's @dfn{public interface} (@pxref{Creating Guile
@@ -118,16 +169,17 @@ 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
-@code{%load-extensions} (REFFIXME). The resulting file name is then
-searched in all directories in the variable @code{%load-path}. For
-example, the @code{(ice-9 popen)} module would result in the filename
-@code{ice-9/popen.scm} and searched in the installation directory of
+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{Install 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?
@@ -149,10 +201,11 @@ address these eventually.
To use a Guile module is to access either its public interface or a
custom interface (@pxref{General Information about Modules}). Both
types of access are handled by the syntactic form @code{use-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 (REFFIXME %load-path).
+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{Install Config}).
An @dfn{interface specification} has one of two forms. The first
variation is simply to name the module, in which case its public
@@ -581,9 +634,6 @@ 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 may work on GNU/Linux:
@smallexample