/[guile]/guile/guile-core/doc/ref/scheme-modules.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-modules.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.10 by ghouston, Wed Jul 10 22:21:25 2002 UTC revision 1.11 by ghouston, Fri Aug 2 22:58:38 2002 UTC
# Line 36  In addition, Guile offers variables as f Line 36  In addition, Guile offers variables as f
36  be used for interacting with the module system.  be used for interacting with the module system.
37    
38  @menu  @menu
39  * Scheme and modules::          How modules are handled in standard Scheme.  * provide and require::         The SLIB feature mechanism.
40    * Environments::                R5RS top-level environments.
41  * The Guile module system::     How Guile does it.  * The Guile module system::     How Guile does it.
42  * Dynamic Libraries::           Loading libraries of compiled code at run time.  * Dynamic Libraries::           Loading libraries of compiled code at run time.
43  * Variables::                   First-class variables.  * Variables::                   First-class variables.
44  @end menu  @end menu
45    
46    @node provide and require
47  @node Scheme and modules  @section provide and require
 @section Scheme and modules  
   
 Scheme, as defined in R5RS, does @emph{not} have a module system at all.  
48    
49  Aubrey Jaffer, mostly to support his portable Scheme library SLIB,  Aubrey Jaffer, mostly to support his portable Scheme library SLIB,
50  implemented a provide/require mechanism for many Scheme implementations.  implemented a provide/require mechanism for many Scheme implementations.
# Line 70  and they would magically become availabl Line 68  and they would magically become availabl
68  names!}  So this method is nice, but not as good as a full-featured  names!}  So this method is nice, but not as good as a full-featured
69  module system.  module system.
70    
71    When SLIB is used with Guile, provide and require can be used to access
72    its facilities.
73    
74    @node Environments
75    @section Environments
76    @cindex environment
77    
78    Scheme, as defined in R5RS, does @emph{not} have a full module system.
79    However it does define the concept of a top-level @dfn{environment}.
80    Such an environment maps identifiers (symbols) to Scheme objects such
81    as procedures and lists: @ref{About Closure}.  In other words, it
82    implements a set of @dfn{bindings}.
83    
84    Environments in R5RS can be passed as the second argument to
85    @code{eval} (@pxref{Fly Evaluation}).  Three procedures are defined to
86    return environments: @code{scheme-report-environment},
87    @code{null-environment} and @code{interaction-environment} (@pxref{Fly
88    Evaluation}).
89    
90    In addition, in Guile any module can be used as an R5RS environment,
91    i.e., passed as the second argument to @code{eval}.
92    
93    @deffn {Scheme Procedure} scheme-report-environment version
94    @deffnx {Scheme Procedure} null-environment version
95    @var{version} must be the exact integer `5', corresponding to revision
96    5 of the Scheme report (the Revised^5 Report on Scheme).
97    @code{scheme-report-environment} returns a specifier for an
98    environment that is empty except for all bindings defined in the
99    report that are either required or both optional and supported by the
100    implementation. @code{null-environment} returns a specifier for an
101    environment that is empty except for the (syntactic) bindings for all
102    syntactic keywords defined in the report that are either required or
103    both optional and supported by the implementation.
104    
105    Currently Guile does not support values of @var{version} for other
106    revisions of the report.
107    
108    The effect of assigning (through the use of @code{eval}) a variable
109    bound in a @code{scheme-report-environment} (for example @code{car})
110    is unspecified.  Currently the environments specified by
111    @code{scheme-report-environment} are not immutable in Guile.
112    @end deffn
113    
114  @node The Guile module system  @node The Guile module system
115  @section The Guile module system  @section The Guile module system
116    
117    The Guile module system extends the concept of environments, discussed
118    in the previous section, with mechanisms to define, use and customise
119    sets of bindings.
120    
121  In 1996 Tom Lord implemented a full-featured module system for Guile which  In 1996 Tom Lord implemented a full-featured module system for Guile which
122  allows loading Scheme source files into a private name space.  This system has  allows loading Scheme source files into a private name space.  This system has
123  been in available since at least Guile version 1.1.  been in available since at least Guile version 1.1.
# Line 101  there is still some flux. Line 145  there is still some flux.
145  @node General Information about Modules  @node General Information about Modules
146  @subsection General Information about Modules  @subsection General Information about Modules
147    
148  A Guile module is a collection of named procedures, variables and  A Guile module can be thought of as a collection of named procedures,
149  macros, altogether called the @dfn{bindings}, since they bind, or  variables and macros.  More precisely, it is a set of @dfn{bindings}
150  associate, a symbol (the name) to a Scheme object (procedure, variable,  of symbols (names) to Scheme objects.
151  or macro).  Within a module, all bindings are visible.  Certain bindings  
152    An environment is a mapping from identifiers (or symbols) to locations,
153    i.e., a set of bindings.
154    There are top-level environments and lexical environments.
155    Environment in which a lambda is excuted is remembered as part of its
156    definition.
157    
158    Within a module, all bindings are visible.  Certain bindings
159  can be declared @dfn{public}, in which case they are added to the  can be declared @dfn{public}, in which case they are added to the
160  module's so-called @dfn{export list}; this set of public bindings is  module's so-called @dfn{export list}; this set of public bindings is
161  called the module's @dfn{public interface} (@pxref{Creating Guile  called the module's @dfn{public interface} (@pxref{Creating Guile
# Line 118  algorithmically @dfn{rename} bindings. Line 169  algorithmically @dfn{rename} bindings.
169  providing module's public interface, the entire export list is available  providing module's public interface, the entire export list is available
170  without renaming (@pxref{Using Guile Modules}).  without renaming (@pxref{Using Guile Modules}).
171    
172  To use a module, it must be found and loaded.  All Guile modules have a  To use a module, it must be found and loaded.  All Guile modules have
173  unique @dfn{module name}, which is a list of one or more symbols.  a unique @dfn{module name}, which is a list of one or more symbols.
174  Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}.  When Guile  Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}.  When
175  searches for the code of a module, it constructs the name of the file to  Guile searches for the code of a module, it constructs the name of the
176  load by concatenating the name elements with slashes between the  file to load by concatenating the name elements with slashes between
177  elements and appending a number of file name extensions from the list  the elements and appending a number of file name extensions from the
178  @code{%load-extensions} (REFFIXME).  The resulting file name is then  list @code{%load-extensions} (@pxref{Loading}).  The resulting file
179  searched in all directories in the variable @code{%load-path}.  For  name is then searched in all directories in the variable
180  example, the @code{(ice-9 popen)} module would result in the filename  @code{%load-path} (@pxref{Install Config}).  For example, the
181  @code{ice-9/popen.scm} and searched in the installation directory of  @code{(ice-9 popen)} module would result in the filename
182    @code{ice-9/popen.scm} and searched in the installation directories of
183  Guile and in all other directories in the load path.  Guile and in all other directories in the load path.
184    
185  @c FIXME::martin:  Not sure about this, maybe someone knows better?  @c FIXME::martin:  Not sure about this, maybe someone knows better?
# Line 149  address these eventually. Line 201  address these eventually.
201  To use a Guile module is to access either its public interface or a  To use a Guile module is to access either its public interface or a
202  custom interface (@pxref{General Information about Modules}).  Both  custom interface (@pxref{General Information about Modules}).  Both
203  types of access are handled by the syntactic form @code{use-modules},  types of access are handled by the syntactic form @code{use-modules},
204  which accepts one or more interface specifications and, upon evaluation,  which accepts one or more interface specifications and, upon
205  arranges for those interfaces to be available to the current module.  evaluation, arranges for those interfaces to be available to the
206  This process may include locating and loading code for a given module if  current module.  This process may include locating and loading code
207  that code has not yet been loaded (REFFIXME %load-path).  for a given module if that code has not yet been loaded, following
208    %load-path (@pxref{Install Config}).
209    
210  An @dfn{interface specification} has one of two forms.  The first  An @dfn{interface specification} has one of two forms.  The first
211  variation is simply to name the module, in which case its public  variation is simply to name the module, in which case its public
# Line 581  converted to a Scheme number and returne Line 634  converted to a Scheme number and returne
634  @code{dynamic-args-call}.  @code{dynamic-args-call}.
635  @end deffn  @end deffn
636    
 When dynamic linking is disabled or not supported on your system,  
 the above functions throw errors, but they are still available.  
   
637  Here is a small example that may work on GNU/Linux:  Here is a small example that may work on GNU/Linux:
638    
639  @smallexample  @smallexample

Legend:
Removed from v.1.10  
changed lines
  Added in v.1.11

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26