/[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.1.2.10 by ossau, Thu Aug 8 22:05:39 2002 UTC revision 1.1.2.11 by ossau, Thu Aug 8 22:35:23 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 636  Each module has its own hash table, some Line 689  Each module has its own hash table, some
689  that maps the names defined in that module to their corresponding  that maps the names defined in that module to their corresponding
690  variable objects.  variable objects.
691    
692  Variables are objects with two fields.  They contain a value and they  A variable is a box-like object that can hold any Scheme value.  It is
693  can contain a symbol, which is the name of the variable.  A variable is  said to be @dfn{undefined} if its box holds a special Scheme value that
694  said to be bound if it does not contain the object denoting unbound  denotes undefined-ness (which is different from all other Scheme values,
695  variables in the value slot.  including for example @code{#f}); otherwise the variable is
696    @dfn{defined}.
697  Variables do not have a read syntax, they have to be created by calling  
698  one of the constructor procedures @code{make-variable} or  On its own, a variable object is anonymous.  A variable is said to be
699  @code{make-undefined-variable} or retrieved by @code{builtin-variable}.  @dfn{bound} when it is associated with a name in some way, usually a
700    symbol in a module obarray.  When this happens, the relationship is
701    mutual: the variable is bound to the name (in that module), and the name
702    (in that module) is bound to the variable.
703    
704    (That's the theory, anyway.  In practice, defined-ness and bound-ness
705    sometimes get confused, because Lisp and Scheme implementations have
706    often conflated --- or deliberately drawn no distinction between --- a
707    name that is unbound and a name that is bound to a variable whose value
708    is undefined.  We will try to be clear about the difference and explain
709    any confusion where it is unavoidable.)
710    
711    Variables do not have a read syntax.  Most commonly they are created and
712    bound implicitly by @code{define} expressions: a top-level @code{define}
713    expression of the form
714    
715    @lisp
716    (define @var{name} @var{value})
717    @end lisp
718    
719    @noindent
720    creates a variable with initial value @var{value} and binds it to the
721    name @var{name} in the current module.  But they can also be created
722    dynamically by calling one of the constructor procedures
723    @code{make-variable} and @code{make-undefined-variable}.
724    
725  First-class variables are especially useful for interacting with the  First-class variables are especially useful for interacting with the
726  current module system (@pxref{The Guile module system}).  current module system (@pxref{The Guile module system}).

Legend:
Removed from v.1.1.2.10  
changed lines
  Added in v.1.1.2.11

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