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. |
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. |
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 |
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? |
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 |
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}). |