Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
992a3879 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2010, 2011, 2012 |
07d83abe MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
07d83abe MV |
7 | @node Modules |
8 | @section Modules | |
9 | @cindex modules | |
10 | ||
11 | When programs become large, naming conflicts can occur when a function | |
12 | or global variable defined in one file has the same name as a function | |
13 | or global variable in another file. Even just a @emph{similarity} | |
14 | between function names can cause hard-to-find bugs, since a programmer | |
15 | might type the wrong function name. | |
16 | ||
17 | The approach used to tackle this problem is called @emph{information | |
18 | encapsulation}, which consists of packaging functional units into a | |
19 | given name space that is clearly separated from other name spaces. | |
20 | @cindex encapsulation | |
21 | @cindex information encapsulation | |
22 | @cindex name space | |
23 | ||
24 | The language features that allow this are usually called @emph{the | |
25 | module system} because programs are broken up into modules that are | |
26 | compiled separately (or loaded separately in an interpreter). | |
27 | ||
28 | Older languages, like C, have limited support for name space | |
29 | manipulation and protection. In C a variable or function is public by | |
30 | default, and can be made local to a module with the @code{static} | |
31 | keyword. But you cannot reference public variables and functions from | |
32 | another module with different names. | |
33 | ||
34 | More advanced module systems have become a common feature in recently | |
35 | designed languages: ML, Python, Perl, and Modula 3 all allow the | |
36 | @emph{renaming} of objects from a foreign module, so they will not | |
37 | clutter the global name space. | |
38 | @cindex name space - private | |
39 | ||
40 | In addition, Guile offers variables as first-class objects. They can | |
41 | be used for interacting with the module system. | |
42 | ||
07d83abe MV |
43 | @menu |
44 | * General Information about Modules:: Guile module basics. | |
45 | * Using Guile Modules:: How to use existing modules. | |
46 | * Creating Guile Modules:: How to package your code into modules. | |
992a3879 | 47 | * Modules and the File System:: Installing modules in the file system. |
dca14012 | 48 | * R6RS Version References:: Using version numbers with modules. |
71194485 | 49 | * R6RS Libraries:: The library and import forms. |
726b8ba3 | 50 | * Variables:: First-class variables. |
992a3879 AW |
51 | * Module System Reflection:: First-class modules. |
52 | * Accessing Modules from C:: How to work with modules with C code. | |
53 | * Included Guile Modules:: Which modules come with Guile? | |
726b8ba3 AW |
54 | * provide and require:: The SLIB feature mechanism. |
55 | * Environments:: R5RS top-level environments. | |
07d83abe MV |
56 | @end menu |
57 | ||
58 | @node General Information about Modules | |
726b8ba3 | 59 | @subsection General Information about Modules |
07d83abe MV |
60 | |
61 | A Guile module can be thought of as a collection of named procedures, | |
62 | variables and macros. More precisely, it is a set of @dfn{bindings} | |
63 | of symbols (names) to Scheme objects. | |
64 | ||
07d83abe MV |
65 | Within a module, all bindings are visible. Certain bindings |
66 | can be declared @dfn{public}, in which case they are added to the | |
67 | module's so-called @dfn{export list}; this set of public bindings is | |
68 | called the module's @dfn{public interface} (@pxref{Creating Guile | |
69 | Modules}). | |
70 | ||
71 | A client module @dfn{uses} a providing module's bindings by either | |
72 | accessing the providing module's public interface, or by building a | |
73 | custom interface (and then accessing that). In a custom interface, the | |
74 | client module can @dfn{select} which bindings to access and can also | |
75 | algorithmically @dfn{rename} bindings. In contrast, when using the | |
76 | providing module's public interface, the entire export list is available | |
77 | without renaming (@pxref{Using Guile Modules}). | |
78 | ||
992a3879 AW |
79 | All Guile modules have a unique @dfn{module name}, for example |
80 | @code{(ice-9 popen)} or @code{(srfi srfi-11)}. Module names are lists | |
81 | of one or more symbols. | |
82 | ||
83 | When Guile goes to use an interface from a module, for example | |
84 | @code{(ice-9 popen)}, Guile first looks to see if it has loaded | |
85 | @code{(ice-9 popen)} for any reason. If the module has not been loaded | |
86 | yet, Guile searches a @dfn{load path} for a file that might define it, | |
87 | and loads that file. | |
07d83abe | 88 | |
992a3879 AW |
89 | The following subsections go into more detail on using, creating, |
90 | installing, and otherwise manipulating modules and the module system. | |
07d83abe MV |
91 | |
92 | @node Using Guile Modules | |
726b8ba3 | 93 | @subsection Using Guile Modules |
07d83abe MV |
94 | |
95 | To use a Guile module is to access either its public interface or a | |
96 | custom interface (@pxref{General Information about Modules}). Both | |
97 | types of access are handled by the syntactic form @code{use-modules}, | |
98 | which accepts one or more interface specifications and, upon evaluation, | |
99 | arranges for those interfaces to be available to the current module. | |
100 | This process may include locating and loading code for a given module if | |
0740cb49 AW |
101 | that code has not yet been loaded, following @code{%load-path} |
102 | (@pxref{Modules and the File System}). | |
07d83abe MV |
103 | |
104 | An @dfn{interface specification} has one of two forms. The first | |
105 | variation is simply to name the module, in which case its public | |
106 | interface is the one accessed. For example: | |
107 | ||
aba0dff5 | 108 | @lisp |
07d83abe | 109 | (use-modules (ice-9 popen)) |
aba0dff5 | 110 | @end lisp |
07d83abe MV |
111 | |
112 | Here, the interface specification is @code{(ice-9 popen)}, and the | |
113 | result is that the current module now has access to @code{open-pipe}, | |
114 | @code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Included | |
115 | Guile Modules}). | |
116 | ||
117 | Note in the previous example that if the current module had already | |
118 | defined @code{open-pipe}, that definition would be overwritten by the | |
119 | definition in @code{(ice-9 popen)}. For this reason (and others), there | |
120 | is a second variation of interface specification that not only names a | |
121 | module to be accessed, but also selects bindings from it and renames | |
122 | them to suit the current module's needs. For example: | |
123 | ||
46bb559d | 124 | @cindex binding renamer |
aba0dff5 | 125 | @lisp |
07d83abe | 126 | (use-modules ((ice-9 popen) |
8d9cb14e NJ |
127 | #:select ((open-pipe . pipe-open) close-pipe) |
128 | #:renamer (symbol-prefix-proc 'unixy:))) | |
aba0dff5 | 129 | @end lisp |
07d83abe MV |
130 | |
131 | Here, the interface specification is more complex than before, and the | |
132 | result is that a custom interface with only two bindings is created and | |
133 | subsequently accessed by the current module. The mapping of old to new | |
134 | names is as follows: | |
135 | ||
136 | @c Use `smallexample' since `table' is ugly. --ttn | |
137 | @smallexample | |
138 | (ice-9 popen) sees: current module sees: | |
139 | open-pipe unixy:pipe-open | |
140 | close-pipe unixy:close-pipe | |
141 | @end smallexample | |
142 | ||
143 | This example also shows how to use the convenience procedure | |
144 | @code{symbol-prefix-proc}. | |
145 | ||
146 | You can also directly refer to bindings in a module by using the | |
147 | @code{@@} syntax. For example, instead of using the | |
148 | @code{use-modules} statement from above and writing | |
149 | @code{unixy:pipe-open} to refer to the @code{pipe-open} from the | |
150 | @code{(ice-9 popen)}, you could also write @code{(@@ (ice-9 popen) | |
151 | open-pipe)}. Thus an alternative to the complete @code{use-modules} | |
152 | statement would be | |
153 | ||
aba0dff5 | 154 | @lisp |
07d83abe MV |
155 | (define unixy:pipe-open (@@ (ice-9 popen) open-pipe)) |
156 | (define unixy:close-pipe (@@ (ice-9 popen) close-pipe)) | |
aba0dff5 | 157 | @end lisp |
07d83abe MV |
158 | |
159 | There is also @code{@@@@}, which can be used like @code{@@}, but does | |
160 | not check whether the variable that is being accessed is actually | |
161 | exported. Thus, @code{@@@@} can be thought of as the impolite version | |
162 | of @code{@@} and should only be used as a last resort or for | |
163 | debugging, for example. | |
164 | ||
165 | Note that just as with a @code{use-modules} statement, any module that | |
166 | has not yet been loaded yet will be loaded when referenced by a | |
167 | @code{@@} or @code{@@@@} form. | |
168 | ||
169 | You can also use the @code{@@} and @code{@@@@} syntaxes as the target | |
170 | of a @code{set!} when the binding refers to a variable. | |
171 | ||
07d83abe MV |
172 | @deffn {Scheme Procedure} symbol-prefix-proc prefix-sym |
173 | Return a procedure that prefixes its arg (a symbol) with | |
174 | @var{prefix-sym}. | |
07d83abe MV |
175 | @end deffn |
176 | ||
07d83abe MV |
177 | @deffn syntax use-modules spec @dots{} |
178 | Resolve each interface specification @var{spec} into an interface and | |
179 | arrange for these to be accessible by the current module. The return | |
180 | value is unspecified. | |
181 | ||
182 | @var{spec} can be a list of symbols, in which case it names a module | |
183 | whose public interface is found and used. | |
184 | ||
185 | @var{spec} can also be of the form: | |
186 | ||
46bb559d | 187 | @cindex binding renamer |
aba0dff5 | 188 | @lisp |
992a3879 | 189 | (MODULE-NAME [#:select SELECTION] [#:renamer RENAMER]) |
aba0dff5 | 190 | @end lisp |
07d83abe MV |
191 | |
192 | in which case a custom interface is newly created and used. | |
193 | @var{module-name} is a list of symbols, as above; @var{selection} is a | |
194 | list of selection-specs; and @var{renamer} is a procedure that takes a | |
195 | symbol and returns its new name. A selection-spec is either a symbol or | |
196 | a pair of symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in | |
197 | the used module and @var{seen} is the name in the using module. Note | |
198 | that @var{seen} is also passed through @var{renamer}. | |
199 | ||
992a3879 AW |
200 | The @code{#:select} and @code{#:renamer} clauses are optional. If both are |
201 | omitted, the returned interface has no bindings. If the @code{#:select} | |
07d83abe MV |
202 | clause is omitted, @var{renamer} operates on the used module's public |
203 | interface. | |
204 | ||
992a3879 | 205 | In addition to the above, @var{spec} can also include a @code{#:version} |
dca14012 JG |
206 | clause, of the form: |
207 | ||
208 | @lisp | |
992a3879 | 209 | #:version VERSION-SPEC |
dca14012 JG |
210 | @end lisp |
211 | ||
992a3879 AW |
212 | where @var{version-spec} is an R6RS-compatible version reference. An |
213 | error will be signaled in the case in which a module with the same name | |
214 | has already been loaded, if that module specifies a version and that | |
215 | version is not compatible with @var{version-spec}. @xref{R6RS Version | |
216 | References}, for more on version references. | |
07d83abe | 217 | |
992a3879 AW |
218 | If the module name is not resolvable, @code{use-modules} will signal an |
219 | error. | |
07d83abe MV |
220 | @end deffn |
221 | ||
222 | @deffn syntax @@ module-name binding-name | |
223 | Refer to the binding named @var{binding-name} in module | |
224 | @var{module-name}. The binding must have been exported by the module. | |
225 | @end deffn | |
226 | ||
227 | @deffn syntax @@@@ module-name binding-name | |
228 | Refer to the binding named @var{binding-name} in module | |
229 | @var{module-name}. The binding must not have been exported by the | |
230 | module. This syntax is only intended for debugging purposes or as a | |
231 | last resort. | |
232 | @end deffn | |
233 | ||
234 | @node Creating Guile Modules | |
726b8ba3 | 235 | @subsection Creating Guile Modules |
07d83abe MV |
236 | |
237 | When you want to create your own modules, you have to take the following | |
238 | steps: | |
239 | ||
240 | @itemize @bullet | |
241 | @item | |
242 | Create a Scheme source file and add all variables and procedures you wish | |
243 | to export, or which are required by the exported procedures. | |
244 | ||
245 | @item | |
246 | Add a @code{define-module} form at the beginning. | |
247 | ||
248 | @item | |
249 | Export all bindings which should be in the public interface, either | |
250 | by using @code{define-public} or @code{export} (both documented below). | |
251 | @end itemize | |
252 | ||
07d83abe | 253 | @deffn syntax define-module module-name [options @dots{}] |
992a3879 | 254 | @var{module-name} is a list of one or more symbols. |
07d83abe | 255 | |
aba0dff5 | 256 | @lisp |
07d83abe | 257 | (define-module (ice-9 popen)) |
aba0dff5 | 258 | @end lisp |
07d83abe MV |
259 | |
260 | @code{define-module} makes this module available to Guile programs under | |
261 | the given @var{module-name}. | |
262 | ||
263 | The @var{options} are keyword/value pairs which specify more about the | |
264 | defined module. The recognized options and their meaning is shown in | |
265 | the following table. | |
266 | ||
07d83abe MV |
267 | @table @code |
268 | @item #:use-module @var{interface-specification} | |
269 | Equivalent to a @code{(use-modules @var{interface-specification})} | |
270 | (@pxref{Using Guile Modules}). | |
271 | ||
950f97ac | 272 | @item #:autoload @var{module} @var{symbol-list} |
65f1345f | 273 | @cindex autoload |
950f97ac KR |
274 | Load @var{module} when any of @var{symbol-list} are accessed. For |
275 | example, | |
276 | ||
277 | @example | |
278 | (define-module (my mod) | |
279 | #:autoload (srfi srfi-1) (partition delete-duplicates)) | |
280 | ... | |
281 | (if something | |
282 | (set! foo (delete-duplicates ...))) | |
283 | @end example | |
284 | ||
a236df75 | 285 | When a module is autoloaded, all its bindings become available. |
950f97ac KR |
286 | @var{symbol-list} is just those that will first trigger the load. |
287 | ||
288 | An autoload is a good way to put off loading a big module until it's | |
289 | really needed, for instance for faster startup or if it will only be | |
290 | needed in certain circumstances. | |
291 | ||
292 | @code{@@} can do a similar thing (@pxref{Using Guile Modules}), but in | |
293 | that case an @code{@@} form must be written every time a binding from | |
294 | the module is used. | |
07d83abe MV |
295 | |
296 | @item #:export @var{list} | |
65f1345f | 297 | @cindex export |
78c22f5e | 298 | Export all identifiers in @var{list} which must be a list of symbols |
992a3879 | 299 | or pairs of symbols. This is equivalent to @code{(export @var{list})} |
78c22f5e | 300 | in the module body. |
07d83abe | 301 | |
46bb559d KR |
302 | @item #:re-export @var{list} |
303 | @cindex re-export | |
304 | Re-export all identifiers in @var{list} which must be a list of | |
78c22f5e JG |
305 | symbols or pairs of symbols. The symbols in @var{list} must be |
306 | imported by the current module from other modules. This is equivalent | |
307 | to @code{re-export} below. | |
46bb559d | 308 | |
46bb559d KR |
309 | @item #:replace @var{list} |
310 | @cindex replace | |
311 | @cindex replacing binding | |
312 | @cindex overriding binding | |
313 | @cindex duplicate binding | |
78c22f5e JG |
314 | Export all identifiers in @var{list} (a list of symbols or pairs of |
315 | symbols) and mark them as @dfn{replacing bindings}. In the module | |
316 | user's name space, this will have the effect of replacing any binding | |
317 | with the same name that is not also ``replacing''. Normally a | |
318 | replacement results in an ``override'' warning message, | |
319 | @code{#:replace} avoids that. | |
46bb559d | 320 | |
d68a81e0 AW |
321 | In general, a module that exports a binding for which the @code{(guile)} |
322 | module already has a definition should use @code{#:replace} instead of | |
323 | @code{#:export}. @code{#:replace}, in a sense, lets Guile know that the | |
324 | module @emph{purposefully} replaces a core binding. It is important to | |
325 | note, however, that this binding replacement is confined to the name | |
326 | space of the module user. In other words, the value of the core binding | |
327 | in question remains unchanged for other modules. | |
328 | ||
329 | Note that although it is often a good idea for the replaced binding to | |
330 | remain compatible with a binding in @code{(guile)}, to avoid surprising | |
331 | the user, sometimes the bindings will be incompatible. For example, | |
332 | SRFI-19 exports its own version of @code{current-time} (@pxref{SRFI-19 | |
333 | Time}) which is not compatible with the core @code{current-time} | |
334 | function (@pxref{Time}). Guile assumes that a user importing a module | |
335 | knows what she is doing, and uses @code{#:replace} for this binding | |
336 | rather than @code{#:export}. | |
e724644d | 337 | |
992a3879 AW |
338 | A @code{#:replace} clause is equivalent to @code{(export! @var{list})} |
339 | in the module body. | |
340 | ||
e724644d MV |
341 | The @code{#:duplicates} (see below) provides fine-grain control about |
342 | duplicate binding handling on the module-user side. | |
46bb559d | 343 | |
dca14012 JG |
344 | @item #:version @var{list} |
345 | @cindex module version | |
346 | Specify a version for the module in the form of @var{list}, a list of | |
347 | zero or more exact, nonnegative integers. The corresponding | |
348 | @code{#:version} option in the @code{use-modules} form allows callers | |
349 | to restrict the value of this option in various ways. | |
350 | ||
46bb559d KR |
351 | @item #:duplicates @var{list} |
352 | @cindex duplicate binding handlers | |
353 | @cindex duplicate binding | |
354 | @cindex overriding binding | |
355 | Tell Guile to handle duplicate bindings for the bindings imported by | |
356 | the current module according to the policy defined by @var{list}, a | |
357 | list of symbols. @var{list} must contain symbols representing a | |
358 | duplicate binding handling policy chosen among the following: | |
359 | ||
360 | @table @code | |
361 | @item check | |
362 | Raises an error when a binding is imported from more than one place. | |
363 | @item warn | |
364 | Issue a warning when a binding is imported from more than one place | |
365 | and leave the responsibility of actually handling the duplication to | |
366 | the next duplicate binding handler. | |
367 | @item replace | |
368 | When a new binding is imported that has the same name as a previously | |
369 | imported binding, then do the following: | |
370 | ||
371 | @enumerate | |
372 | @item | |
373 | @cindex replacing binding | |
374 | If the old binding was said to be @dfn{replacing} (via the | |
375 | @code{#:replace} option above) and the new binding is not replacing, | |
376 | the keep the old binding. | |
377 | @item | |
378 | If the old binding was not said to be replacing and the new binding is | |
379 | replacing, then replace the old binding with the new one. | |
380 | @item | |
381 | If neither the old nor the new binding is replacing, then keep the old | |
382 | one. | |
383 | @end enumerate | |
384 | ||
385 | @item warn-override-core | |
386 | Issue a warning when a core binding is being overwritten and actually | |
387 | override the core binding with the new one. | |
388 | @item first | |
389 | In case of duplicate bindings, the firstly imported binding is always | |
390 | the one which is kept. | |
391 | @item last | |
392 | In case of duplicate bindings, the lastly imported binding is always | |
393 | the one which is kept. | |
394 | @item noop | |
395 | In case of duplicate bindings, leave the responsibility to the next | |
396 | duplicate handler. | |
397 | @end table | |
398 | ||
399 | If @var{list} contains more than one symbol, then the duplicate | |
400 | binding handlers which appear first will be used first when resolving | |
401 | a duplicate binding situation. As mentioned above, some resolution | |
402 | policies may explicitly leave the responsibility of handling the | |
403 | duplication to the next handler in @var{list}. | |
404 | ||
992a3879 AW |
405 | If GOOPS has been loaded before the @code{#:duplicates} clause is |
406 | processed, there are additional strategies available for dealing with | |
407 | generic functions. @xref{Merging Generics}, for more information. | |
408 | ||
46bb559d KR |
409 | @findex default-duplicate-binding-handler |
410 | The default duplicate binding resolution policy is given by the | |
411 | @code{default-duplicate-binding-handler} procedure, and is | |
412 | ||
aba0dff5 | 413 | @lisp |
46bb559d | 414 | (replace warn-override-core warn last) |
aba0dff5 | 415 | @end lisp |
46bb559d | 416 | |
07d83abe | 417 | @item #:pure |
65f1345f | 418 | @cindex pure module |
07d83abe MV |
419 | Create a @dfn{pure} module, that is a module which does not contain any |
420 | of the standard procedure bindings except for the syntax forms. This is | |
421 | useful if you want to create @dfn{safe} modules, that is modules which | |
422 | do not know anything about dangerous procedures. | |
423 | @end table | |
424 | ||
425 | @end deffn | |
07d83abe MV |
426 | |
427 | @deffn syntax export variable @dots{} | |
78c22f5e JG |
428 | Add all @var{variable}s (which must be symbols or pairs of symbols) to |
429 | the list of exported bindings of the current module. If @var{variable} | |
430 | is a pair, its @code{car} gives the name of the variable as seen by the | |
431 | current module and its @code{cdr} specifies a name for the binding in | |
432 | the current module's public interface. | |
07d83abe MV |
433 | @end deffn |
434 | ||
07d83abe MV |
435 | @deffn syntax define-public @dots{} |
436 | Equivalent to @code{(begin (define foo ...) (export foo))}. | |
437 | @end deffn | |
07d83abe | 438 | |
46bb559d | 439 | @deffn syntax re-export variable @dots{} |
78c22f5e JG |
440 | Add all @var{variable}s (which must be symbols or pairs of symbols) to |
441 | the list of re-exported bindings of the current module. Pairs of | |
442 | symbols are handled as in @code{export}. Re-exported bindings must be | |
443 | imported by the current module from some other module. | |
46bb559d KR |
444 | @end deffn |
445 | ||
992a3879 AW |
446 | @deffn syntax export! variable @dots{} |
447 | Like @code{export}, but marking the exported variables as replacing. | |
448 | Using a module with replacing bindings will cause any existing bindings | |
449 | to be replaced without issuing any warnings. See the discussion of | |
450 | @code{#:replace} above. | |
cdf1ad3b MV |
451 | @end deffn |
452 | ||
992a3879 AW |
453 | @node Modules and the File System |
454 | @subsection Modules and the File System | |
07d83abe | 455 | |
992a3879 AW |
456 | Typical programs only use a small subset of modules installed on a Guile |
457 | system. In order to keep startup time down, Guile only loads modules | |
458 | when a program uses them, on demand. | |
e376f9e5 | 459 | |
992a3879 AW |
460 | When a program evaluates @code{(use-modules (ice-9 popen))}, and the |
461 | module is not loaded, Guile searches for a conventionally-named file | |
462 | from in the @dfn{load path}. | |
07d83abe | 463 | |
992a3879 AW |
464 | In this case, loading @code{(ice-9 popen)} will eventually cause Guile |
465 | to run @code{(primitive-load-path "ice-9/popen")}. | |
466 | @code{primitive-load-path} will search for a file @file{ice-9/popen} in | |
0740cb49 | 467 | the @code{%load-path} (@pxref{Load Paths}). For each directory in |
992a3879 AW |
468 | @code{%load-path}, Guile will try to find the file name, concatenated |
469 | with the extensions from @code{%load-extensions}. By default, this will | |
470 | cause Guile to @code{stat} @file{ice-9/popen.scm}, and then | |
925172cf | 471 | @file{ice-9/popen}. @xref{Load Paths}, for more on |
992a3879 | 472 | @code{primitive-load-path}. |
e376f9e5 | 473 | |
992a3879 AW |
474 | If a corresponding compiled @file{.go} file is found in the |
475 | @code{%load-compiled-path} or in the fallback path, and is as fresh as | |
476 | the source file, it will be loaded instead of the source file. If no | |
477 | compiled file is found, Guile may try to compile the source file and | |
478 | cache away the resulting @file{.go} file. @xref{Compilation}, for more | |
479 | on compilation. | |
07d83abe | 480 | |
992a3879 AW |
481 | Once Guile finds a suitable source or compiled file is found, the file |
482 | will be loaded. If, after loading the file, the module under | |
483 | consideration is still not defined, Guile will signal an error. | |
e376f9e5 | 484 | |
992a3879 AW |
485 | For more information on where and how to install Scheme modules, |
486 | @xref{Installing Site Packages}. | |
07d83abe MV |
487 | |
488 | ||
dca14012 | 489 | @node R6RS Version References |
726b8ba3 | 490 | @subsection R6RS Version References |
dca14012 JG |
491 | |
492 | Guile's module system includes support for locating modules based on | |
493 | a declared version specifier of the same form as the one described in | |
494 | R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The Revised^6 | |
495 | Report on the Algorithmic Language Scheme}). By using the | |
496 | @code{#:version} keyword in a @code{define-module} form, a module may | |
497 | specify a version as a list of zero or more exact, nonnegative integers. | |
498 | ||
499 | This version can then be used to locate the module during the module | |
500 | search process. Client modules and callers of the @code{use-modules} | |
501 | function may specify constraints on the versions of target modules by | |
502 | providing a @dfn{version reference}, which has one of the following | |
503 | forms: | |
504 | ||
505 | @lisp | |
506 | (@var{sub-version-reference} ...) | |
507 | (and @var{version-reference} ...) | |
508 | (or @var{version-reference} ...) | |
509 | (not @var{version-reference}) | |
510 | @end lisp | |
511 | ||
512 | in which @var{sub-version-reference} is in turn one of: | |
513 | ||
514 | @lisp | |
515 | (@var{sub-version}) | |
516 | (>= @var{sub-version}) | |
517 | (<= @var{sub-version}) | |
518 | (and @var{sub-version-reference} ...) | |
519 | (or @var{sub-version-reference} ...) | |
520 | (not @var{sub-version-reference}) | |
521 | @end lisp | |
522 | ||
523 | in which @var{sub-version} is an exact, nonnegative integer as above. A | |
524 | version reference matches a declared module version if each element of | |
525 | the version reference matches a corresponding element of the module | |
526 | version, according to the following rules: | |
527 | ||
528 | @itemize @bullet | |
529 | @item | |
530 | The @code{and} sub-form matches a version or version element if every | |
531 | element in the tail of the sub-form matches the specified version or | |
532 | version element. | |
533 | ||
534 | @item | |
535 | The @code{or} sub-form matches a version or version element if any | |
536 | element in the tail of the sub-form matches the specified version or | |
537 | version element. | |
538 | ||
539 | @item | |
540 | The @code{not} sub-form matches a version or version element if the tail | |
541 | of the sub-form does not match the version or version element. | |
542 | ||
543 | @item | |
544 | The @code{>=} sub-form matches a version element if the element is | |
545 | greater than or equal to the @var{sub-version} in the tail of the | |
546 | sub-form. | |
547 | ||
548 | @item | |
549 | The @code{<=} sub-form matches a version element if the version is less | |
550 | than or equal to the @var{sub-version} in the tail of the sub-form. | |
551 | ||
552 | @item | |
553 | A @var{sub-version} matches a version element if one is @var{eqv?} to | |
554 | the other. | |
555 | @end itemize | |
556 | ||
557 | For example, a module declared as: | |
558 | ||
559 | @lisp | |
560 | (define-module (mylib mymodule) #:version (1 2 0)) | |
561 | @end lisp | |
562 | ||
563 | would be successfully loaded by any of the following @code{use-modules} | |
564 | expressions: | |
565 | ||
566 | @lisp | |
567 | (use-modules ((mylib mymodule) #:version (1 2 (>= 0)))) | |
568 | (use-modules ((mylib mymodule) #:version (or (1 2 0) (1 2 1)))) | |
569 | (use-modules ((mylib mymodule) #:version ((and (>= 1) (not 2)) 2 0))) | |
570 | @end lisp | |
571 | ||
572 | ||
71194485 JG |
573 | @node R6RS Libraries |
574 | @subsection R6RS Libraries | |
575 | ||
576 | In addition to the API described in the previous sections, you also | |
43d6eb75 | 577 | have the option to create modules using the portable @code{library} form |
71194485 JG |
578 | described in R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The |
579 | Revised^6 Report on the Algorithmic Language Scheme}), and to import | |
580 | libraries created in this format by other programmers. Guile's R6RS | |
43d6eb75 JG |
581 | library implementation takes advantage of the flexibility built into the |
582 | module system by expanding the R6RS library form into a corresponding | |
583 | Guile @code{define-module} form that specifies equivalent import and | |
584 | export requirements and includes the same body expressions. The library | |
585 | expression: | |
71194485 JG |
586 | |
587 | @lisp | |
588 | (library (mylib (1 2)) | |
589 | (import (otherlib (3))) | |
590 | (export mybinding)) | |
591 | @end lisp | |
592 | ||
593 | is equivalent to the module definition: | |
594 | ||
595 | @lisp | |
596 | (define-module (mylib) | |
597 | #:version (1 2) | |
598 | #:use-module ((otherlib) #:version (3)) | |
599 | #:export (mybinding)) | |
600 | @end lisp | |
601 | ||
602 | Central to the mechanics of R6RS libraries is the concept of import | |
43d6eb75 | 603 | and export @dfn{levels}, which control the visibility of bindings at |
71194485 JG |
604 | various phases of a library's lifecycle --- macros necessary to |
605 | expand forms in the library's body need to be available at expand | |
606 | time; variables used in the body of a procedure exported by the | |
607 | library must be available at runtime. R6RS specifies the optional | |
608 | @code{for} sub-form of an @emph{import set} specification (see below) | |
609 | as a mechanism by which a library author can indicate that a | |
610 | particular library import should take place at a particular phase | |
611 | with respect to the lifecycle of the importing library. | |
612 | ||
c8eb2797 | 613 | Guile's library implementation uses a technique called |
43d6eb75 JG |
614 | @dfn{implicit phasing} (first described by Abdulaziz Ghuloum and R. |
615 | Kent Dybvig), which allows the expander and compiler to automatically | |
616 | determine the necessary visibility of a binding imported from another | |
617 | library. As such, the @code{for} sub-form described below is ignored by | |
618 | Guile (but may be required by Schemes in which phasing is explicit). | |
71194485 | 619 | |
43d6eb75 | 620 | @deffn {Scheme Syntax} library name (export export-spec ...) (import import-spec ...) body ... |
71194485 JG |
621 | Defines a new library with the specified name, exports, and imports, |
622 | and evaluates the specified body expressions in this library's | |
623 | environment. | |
624 | ||
625 | The library @var{name} is a non-empty list of identifiers, optionally | |
626 | ending with a version specification of the form described above | |
627 | (@pxref{Creating Guile Modules}). | |
628 | ||
629 | Each @var{export-spec} is the name of a variable defined or imported | |
630 | by the library, or must take the form | |
631 | @code{(rename (internal-name external-name) ...)}, where the | |
632 | identifier @var{internal-name} names a variable defined or imported | |
633 | by the library and @var{external-name} is the name by which the | |
634 | variable is seen by importing libraries. | |
635 | ||
43d6eb75 | 636 | Each @var{import-spec} must be either an @dfn{import set} (see below) |
71194485 JG |
637 | or must be of the form @code{(for import-set import-level ...)}, |
638 | where each @var{import-level} is one of: | |
639 | ||
640 | @lisp | |
641 | run | |
642 | expand | |
643 | (meta @var{level}) | |
644 | @end lisp | |
645 | ||
646 | where @var{level} is an integer. Note that since Guile does not | |
647 | require explicit phase specification, any @var{import-set}s found | |
648 | inside of @code{for} sub-forms will be ``unwrapped'' during | |
649 | expansion and processed as if they had been specified directly. | |
650 | ||
651 | Import sets in turn take one of the following forms: | |
652 | ||
653 | @lisp | |
654 | @var{library-reference} | |
655 | (library @var{library-reference}) | |
656 | (only @var{import-set} @var{identifier} ...) | |
657 | (except @var{import-set} @var{identifier} ...) | |
658 | (prefix @var{import-set} @var{identifier}) | |
659 | (rename @var{import-set} (@var{internal-identifier} @var{external-identifier}) ...) | |
660 | @end lisp | |
661 | ||
662 | where @var{library-reference} is a non-empty list of identifiers | |
663 | ending with an optional version reference (@pxref{R6RS Version | |
664 | References}), and the other sub-forms have the following semantics, | |
665 | defined recursively on nested @var{import-set}s: | |
666 | ||
667 | @itemize @bullet | |
668 | ||
669 | @item | |
670 | The @code{library} sub-form is used to specify libraries for import | |
671 | whose names begin with the identifier ``library.'' | |
672 | ||
673 | @item | |
674 | The @code{only} sub-form imports only the specified @var{identifier}s | |
675 | from the given @var{import-set}. | |
676 | ||
677 | @item | |
678 | The @code{except} sub-form imports all of the bindings exported by | |
679 | @var{import-set} except for those that appear in the specified list | |
680 | of @var{identifier}s. | |
681 | ||
682 | @item | |
683 | The @code{prefix} sub-form imports all of the bindings exported | |
684 | by @var{import-set}, first prefixing them with the specified | |
685 | @var{identifier}. | |
686 | ||
687 | @item | |
688 | The @code{rename} sub-form imports all of the identifiers exported | |
689 | by @var{import-set}. The binding for each @var{internal-identifier} | |
690 | among these identifiers is made visible to the importing library as | |
691 | the corresponding @var{external-identifier}; all other bindings are | |
692 | imported using the names provided by @var{import-set}. | |
693 | ||
694 | @end itemize | |
695 | ||
696 | Note that because Guile translates R6RS libraries into module | |
697 | definitions, an import specification may be used to declare a | |
698 | dependency on a native Guile module --- although doing so may make | |
699 | your libraries less portable to other Schemes. | |
700 | ||
701 | @end deffn | |
702 | ||
43d6eb75 | 703 | @deffn {Scheme Syntax} import import-spec ... |
71194485 JG |
704 | Import into the current environment the libraries specified by the |
705 | given import specifications, where each @var{import-spec} takes the | |
43d6eb75 | 706 | same form as in the @code{library} form described above. |
71194485 JG |
707 | @end deffn |
708 | ||
709 | ||
992a3879 AW |
710 | @node Variables |
711 | @subsection Variables | |
712 | @tpindex Variables | |
713 | ||
714 | Each module has its own hash table, sometimes known as an @dfn{obarray}, | |
715 | that maps the names defined in that module to their corresponding | |
716 | variable objects. | |
717 | ||
718 | A variable is a box-like object that can hold any Scheme value. It is | |
719 | said to be @dfn{undefined} if its box holds a special Scheme value that | |
720 | denotes undefined-ness (which is different from all other Scheme values, | |
721 | including for example @code{#f}); otherwise the variable is | |
722 | @dfn{defined}. | |
723 | ||
724 | On its own, a variable object is anonymous. A variable is said to be | |
725 | @dfn{bound} when it is associated with a name in some way, usually a | |
726 | symbol in a module obarray. When this happens, the name is said to be | |
727 | bound to the variable, in that module. | |
728 | ||
729 | (That's the theory, anyway. In practice, defined-ness and bound-ness | |
730 | sometimes get confused, because Lisp and Scheme implementations have | |
731 | often conflated --- or deliberately drawn no distinction between --- a | |
732 | name that is unbound and a name that is bound to a variable whose value | |
733 | is undefined. We will try to be clear about the difference and explain | |
734 | any confusion where it is unavoidable.) | |
735 | ||
736 | Variables do not have a read syntax. Most commonly they are created and | |
737 | bound implicitly by @code{define} expressions: a top-level @code{define} | |
738 | expression of the form | |
739 | ||
740 | @lisp | |
741 | (define @var{name} @var{value}) | |
742 | @end lisp | |
743 | ||
744 | @noindent | |
745 | creates a variable with initial value @var{value} and binds it to the | |
746 | name @var{name} in the current module. But they can also be created | |
747 | dynamically by calling one of the constructor procedures | |
748 | @code{make-variable} and @code{make-undefined-variable}. | |
749 | ||
750 | @deffn {Scheme Procedure} make-undefined-variable | |
751 | @deffnx {C Function} scm_make_undefined_variable () | |
752 | Return a variable that is initially unbound. | |
753 | @end deffn | |
754 | ||
755 | @deffn {Scheme Procedure} make-variable init | |
756 | @deffnx {C Function} scm_make_variable (init) | |
757 | Return a variable initialized to value @var{init}. | |
758 | @end deffn | |
759 | ||
760 | @deffn {Scheme Procedure} variable-bound? var | |
761 | @deffnx {C Function} scm_variable_bound_p (var) | |
762 | Return @code{#t} iff @var{var} is bound to a value. | |
763 | Throws an error if @var{var} is not a variable object. | |
764 | @end deffn | |
765 | ||
766 | @deffn {Scheme Procedure} variable-ref var | |
767 | @deffnx {C Function} scm_variable_ref (var) | |
768 | Dereference @var{var} and return its value. | |
769 | @var{var} must be a variable object; see @code{make-variable} | |
770 | and @code{make-undefined-variable}. | |
771 | @end deffn | |
772 | ||
773 | @deffn {Scheme Procedure} variable-set! var val | |
774 | @deffnx {C Function} scm_variable_set_x (var, val) | |
775 | Set the value of the variable @var{var} to @var{val}. | |
776 | @var{var} must be a variable object, @var{val} can be any | |
777 | value. Return an unspecified value. | |
778 | @end deffn | |
779 | ||
780 | @deffn {Scheme Procedure} variable-unset! var | |
781 | @deffnx {C Function} scm_variable_unset_x (var) | |
782 | Unset the value of the variable @var{var}, leaving @var{var} unbound. | |
783 | @end deffn | |
784 | ||
785 | @deffn {Scheme Procedure} variable? obj | |
786 | @deffnx {C Function} scm_variable_p (obj) | |
787 | Return @code{#t} iff @var{obj} is a variable object, else | |
788 | return @code{#f}. | |
789 | @end deffn | |
790 | ||
791 | ||
792 | @node Module System Reflection | |
793 | @subsection Module System Reflection | |
794 | ||
795 | The previous sections have described a declarative view of the module | |
796 | system. You can also work with it programmatically by accessing and | |
797 | modifying various parts of the Scheme objects that Guile uses to | |
798 | implement the module system. | |
799 | ||
800 | At any time, there is a @dfn{current module}. This module is the one | |
801 | where a top-level @code{define} and similar syntax will add new | |
802 | bindings. You can find other module objects with @code{resolve-module}, | |
803 | for example. | |
804 | ||
805 | These module objects can be used as the second argument to @code{eval}. | |
806 | ||
807 | @deffn {Scheme Procedure} current-module | |
808 | @deffnx {C Function} scm_current_module () | |
809 | Return the current module object. | |
810 | @end deffn | |
811 | ||
812 | @deffn {Scheme Procedure} set-current-module module | |
813 | @deffnx {C Function} scm_set_current_module (module) | |
814 | Set the current module to @var{module} and return | |
815 | the previous current module. | |
816 | @end deffn | |
817 | ||
818 | @deffn {Scheme Procedure} save-module-excursion thunk | |
819 | Call @var{thunk} within a @code{dynamic-wind} such that the module that | |
820 | is current at invocation time is restored when @var{thunk}'s dynamic | |
821 | extent is left (@pxref{Dynamic Wind}). | |
822 | ||
823 | More precisely, if @var{thunk} escapes non-locally, the current module | |
824 | (at the time of escape) is saved, and the original current module (at | |
825 | the time @var{thunk}'s dynamic extent was last entered) is restored. If | |
826 | @var{thunk}'s dynamic extent is re-entered, then the current module is | |
827 | saved, and the previously saved inner module is set current again. | |
828 | @end deffn | |
829 | ||
830 | @deffn {Scheme Procedure} resolve-module name [autoload=#t] [version=#f] [#:ensure=#t] | |
831 | @deffnx {C Function} scm_resolve_module (name) | |
832 | Find the module named @var{name} and return it. When it has not already | |
833 | been defined and @var{autoload} is true, try to auto-load it. When it | |
834 | can't be found that way either, create an empty module if @var{ensure} | |
835 | is true, otherwise return @code{#f}. If @var{version} is true, ensure | |
836 | that the resulting module is compatible with the given version reference | |
837 | (@pxref{R6RS Version References}). The name is a list of symbols. | |
838 | @end deffn | |
839 | ||
840 | @deffn {Scheme Procedure} resolve-interface name [#:select=#f] [#:hide='()] [#:select=()] [#:prefix=#f] [#:renamer] [#:version=#f] | |
841 | Find the module named @var{name} as with @code{resolve-module} and | |
842 | return its interface. The interface of a module is also a module | |
843 | object, but it contains only the exported bindings. | |
844 | @end deffn | |
845 | ||
846 | @deffn {Scheme Procedure} module-uses module | |
847 | Return a list of the interfaces used by @var{module}. | |
848 | @end deffn | |
849 | ||
850 | @deffn {Scheme Procedure} module-use! module interface | |
851 | Add @var{interface} to the front of the use-list of @var{module}. Both | |
852 | arguments should be module objects, and @var{interface} should very | |
853 | likely be a module returned by @code{resolve-interface}. | |
854 | @end deffn | |
855 | ||
856 | @deffn {Scheme Procedure} reload-module module | |
857 | Revisit the source file that corresponds to @var{module}. Raises an | |
858 | error if no source file is associated with the given module. | |
859 | @end deffn | |
860 | ||
861 | As mentioned in the previous section, modules contain a mapping between | |
862 | identifiers (as symbols) and storage locations (as variables). Guile | |
863 | defines a number of procedures to allow access to this mapping. If you | |
864 | are programming in C, @ref{Accessing Modules from C}. | |
865 | ||
866 | @deffn {Scheme Procedure} module-variable module name | |
867 | Return the variable bound to @var{name} (a symbol) in @var{module}, or | |
868 | @code{#f} if @var{name} is unbound. | |
869 | @end deffn | |
870 | ||
871 | @deffn {Scheme Procedure} module-add! module name var | |
872 | Define a new binding between @var{name} (a symbol) and @var{var} (a | |
873 | variable) in @var{module}. | |
874 | @end deffn | |
875 | ||
876 | @deffn {Scheme Procedure} module-ref module name | |
877 | Look up the value bound to @var{name} in @var{module}. Like | |
878 | @code{module-variable}, but also does a @code{variable-ref} on the | |
879 | resulting variable, raising an error if @var{name} is unbound. | |
880 | @end deffn | |
881 | ||
882 | @deffn {Scheme Procedure} module-define! module name value | |
883 | Locally bind @var{name} to @var{value} in @var{module}. If @var{name} | |
884 | was already locally bound in @var{module}, i.e., defined locally and not | |
885 | by an imported module, the value stored in the existing variable will be | |
886 | updated. Otherwise, a new variable will be added to the module, via | |
887 | @code{module-add!}. | |
888 | @end deffn | |
889 | ||
890 | @deffn {Scheme Procedure} module-set! module name value | |
891 | Update the binding of @var{name} in @var{module} to @var{value}, raising | |
892 | an error if @var{name} is not already bound in @var{module}. | |
893 | @end deffn | |
894 | ||
895 | There are many other reflective procedures available in the default | |
896 | environment. If you find yourself using one of them, please contact the | |
897 | Guile developers so that we can commit to stability for that interface. | |
898 | ||
899 | ||
07d83abe | 900 | @node Accessing Modules from C |
726b8ba3 | 901 | @subsection Accessing Modules from C |
07d83abe MV |
902 | |
903 | The last sections have described how modules are used in Scheme code, | |
904 | which is the recommended way of creating and accessing modules. You | |
905 | can also work with modules from C, but it is more cumbersome. | |
906 | ||
907 | The following procedures are available. | |
908 | ||
7af1ba2f | 909 | @deftypefn {C Function} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data}) |
07d83abe MV |
910 | Call @var{func} and make @var{module} the current module during the |
911 | call. The argument @var{data} is passed to @var{func}. The return | |
912 | value of @code{scm_c_call_with_current_module} is the return value of | |
913 | @var{func}. | |
914 | @end deftypefn | |
915 | ||
7af1ba2f LC |
916 | @deftypefn {C Function} SCM scm_public_variable (SCM @var{module_name}, SCM @var{name}) |
917 | @deftypefnx {C Function} SCM scm_c_public_variable ({const char *}@var{module_name}, {const char *}@var{name}) | |
831e6782 AW |
918 | Find a the variable bound to the symbol @var{name} in the public |
919 | interface of the module named @var{module_name}. | |
920 | ||
7af1ba2f | 921 | @var{module_name} should be a list of symbols, when represented as a |
831e6782 AW |
922 | Scheme object, or a space-separated string, in the @code{const char *} |
923 | case. See @code{scm_c_define_module} below, for more examples. | |
924 | ||
925 | Signals an error if no module was found with the given name. If | |
926 | @var{name} is not bound in the module, just returns @code{#f}. | |
927 | @end deftypefn | |
928 | ||
7af1ba2f LC |
929 | @deftypefn {C Function} SCM scm_private_variable (SCM @var{module_name}, SCM @var{name}) |
930 | @deftypefnx {C Function} SCM scm_c_private_variable ({const char *}@var{module_name}, {const char *}@var{name}) | |
831e6782 AW |
931 | Like @code{scm_public_variable}, but looks in the internals of the |
932 | module named @var{module_name} instead of the public interface. | |
933 | Logically, these procedures should only be called on modules you write. | |
934 | @end deftypefn | |
935 | ||
7af1ba2f LC |
936 | @deftypefn {C Function} SCM scm_public_lookup (SCM @var{module_name}, SCM @var{name}) |
937 | @deftypefnx {C Function} SCM scm_c_public_lookup ({const char *}@var{module_name}, {const char *}@var{name}) | |
938 | @deftypefnx {C Function} SCM scm_private_lookup (SCM @var{module_name}, SCM @var{name}) | |
939 | @deftypefnx {C Function} SCM scm_c_private_lookup ({const char *}@var{module_name}, {const char *}@var{name}) | |
831e6782 AW |
940 | Like @code{scm_public_variable} or @code{scm_private_variable}, but if |
941 | the @var{name} is not bound in the module, signals an error. Returns a | |
942 | variable, always. | |
943 | ||
944 | @example | |
945 | SCM my_eval_string (SCM str) | |
946 | @{ | |
947 | static SCM eval_string_var = SCM_BOOL_F; | |
948 | ||
949 | if (scm_is_false (eval_string_var)) | |
950 | eval_string_var = | |
951 | scm_c_public_lookup ("ice-9 eval-string", "eval-string"); | |
952 | ||
953 | return scm_call_1 (scm_variable_ref (eval_string_var), str); | |
954 | @} | |
955 | @end example | |
956 | @end deftypefn | |
957 | ||
7af1ba2f LC |
958 | @deftypefn {C Function} SCM scm_public_ref (SCM @var{module_name}, SCM @var{name}) |
959 | @deftypefnx {C Function} SCM scm_c_public_ref ({const char *}@var{module_name}, {const char *}@var{name}) | |
960 | @deftypefnx {C Function} SCM scm_private_ref (SCM @var{module_name}, SCM @var{name}) | |
961 | @deftypefnx {C Function} SCM scm_c_private_ref ({const char *}@var{module_name}, {const char *}@var{name}) | |
831e6782 AW |
962 | Like @code{scm_public_lookup} or @code{scm_private_lookup}, but |
963 | additionally dereferences the variable. If the variable object is | |
964 | unbound, signals an error. Returns the value bound to @var{name} in | |
965 | @var{module}. | |
966 | @end deftypefn | |
967 | ||
968 | In addition, there are a number of other lookup-related procedures. We | |
969 | suggest that you use the @code{scm_public_} and @code{scm_private_} | |
970 | family of procedures instead, if possible. | |
971 | ||
7af1ba2f | 972 | @deftypefn {C Function} SCM scm_c_lookup ({const char *}@var{name}) |
07d83abe MV |
973 | Return the variable bound to the symbol indicated by @var{name} in the |
974 | current module. If there is no such binding or the symbol is not | |
975 | bound to a variable, signal an error. | |
976 | @end deftypefn | |
977 | ||
7af1ba2f | 978 | @deftypefn {C Function} SCM scm_lookup (SCM @var{name}) |
07d83abe MV |
979 | Like @code{scm_c_lookup}, but the symbol is specified directly. |
980 | @end deftypefn | |
981 | ||
7af1ba2f LC |
982 | @deftypefn {C Function} SCM scm_c_module_lookup (SCM @var{module}, {const char *}@var{name}) |
983 | @deftypefnx {C Function} SCM scm_module_lookup (SCM @var{module}, SCM @var{name}) | |
07d83abe MV |
984 | Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified |
985 | module is used instead of the current one. | |
986 | @end deftypefn | |
987 | ||
7af1ba2f | 988 | @deftypefn {C Function} SCM scm_module_variable (SCM @var{module}, SCM @var{name}) |
831e6782 AW |
989 | Like @code{scm_module_lookup}, but if the binding does not exist, just |
990 | returns @code{#f} instead of raising an error. | |
991 | @end deftypefn | |
992 | ||
993 | To define a value, use @code{scm_define}: | |
994 | ||
7af1ba2f | 995 | @deftypefn {C Function} SCM scm_c_define ({const char *}@var{name}, SCM @var{val}) |
07d83abe MV |
996 | Bind the symbol indicated by @var{name} to a variable in the current |
997 | module and set that variable to @var{val}. When @var{name} is already | |
998 | bound to a variable, use that. Else create a new variable. | |
999 | @end deftypefn | |
1000 | ||
7af1ba2f | 1001 | @deftypefn {C Function} SCM scm_define (SCM @var{name}, SCM @var{val}) |
07d83abe MV |
1002 | Like @code{scm_c_define}, but the symbol is specified directly. |
1003 | @end deftypefn | |
1004 | ||
7af1ba2f LC |
1005 | @deftypefn {C Function} SCM scm_c_module_define (SCM @var{module}, {const char *}@var{name}, SCM @var{val}) |
1006 | @deftypefnx {C Function} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val}) | |
07d83abe MV |
1007 | Like @code{scm_c_define} and @code{scm_define}, but the specified |
1008 | module is used instead of the current one. | |
1009 | @end deftypefn | |
1010 | ||
7af1ba2f | 1011 | @deftypefn {C Function} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable}) |
07d83abe MV |
1012 | Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @var{#f}. |
1013 | @end deftypefn | |
1014 | ||
7af1ba2f | 1015 | @deftypefn {C Function} SCM scm_c_define_module ({const char *}@var{name}, void (*@var{init})(void *), void *@var{data}) |
07d83abe MV |
1016 | Define a new module named @var{name} and make it current while |
1017 | @var{init} is called, passing it @var{data}. Return the module. | |
1018 | ||
1019 | The parameter @var{name} is a string with the symbols that make up | |
1020 | the module name, separated by spaces. For example, @samp{"foo bar"} names | |
1021 | the module @samp{(foo bar)}. | |
1022 | ||
1023 | When there already exists a module named @var{name}, it is used | |
1024 | unchanged, otherwise, an empty module is created. | |
1025 | @end deftypefn | |
1026 | ||
7af1ba2f | 1027 | @deftypefn {C Function} SCM scm_c_resolve_module ({const char *}@var{name}) |
07d83abe MV |
1028 | Find the module name @var{name} and return it. When it has not |
1029 | already been defined, try to auto-load it. When it can't be found | |
1030 | that way either, create an empty module. The name is interpreted as | |
1031 | for @code{scm_c_define_module}. | |
1032 | @end deftypefn | |
1033 | ||
7af1ba2f | 1034 | @deftypefn {C Function} SCM scm_c_use_module ({const char *}@var{name}) |
07d83abe MV |
1035 | Add the module named @var{name} to the uses list of the current |
1036 | module, as with @code{(use-modules @var{name})}. The name is | |
1037 | interpreted as for @code{scm_c_define_module}. | |
1038 | @end deftypefn | |
1039 | ||
7af1ba2f | 1040 | @deftypefn {C Function} SCM scm_c_export ({const char *}@var{name}, ...) |
07d83abe MV |
1041 | Add the bindings designated by @var{name}, ... to the public interface |
1042 | of the current module. The list of names is terminated by | |
1043 | @code{NULL}. | |
1044 | @end deftypefn | |
1045 | ||
ef5f9163 | 1046 | |
992a3879 AW |
1047 | @node Included Guile Modules |
1048 | @subsection Included Guile Modules | |
07d83abe | 1049 | |
992a3879 AW |
1050 | Some modules are included in the Guile distribution; here are references |
1051 | to the entries in this manual which describe them in more detail: | |
07d83abe | 1052 | |
992a3879 AW |
1053 | @table @strong |
1054 | @item boot-9 | |
1055 | boot-9 is Guile's initialization module, and it is always loaded when | |
1056 | Guile starts up. | |
07d83abe | 1057 | |
992a3879 AW |
1058 | @item (ice-9 expect) |
1059 | Actions based on matching input from a port (@pxref{Expect}). | |
07d83abe | 1060 | |
992a3879 AW |
1061 | @item (ice-9 format) |
1062 | Formatted output in the style of Common Lisp (@pxref{Formatted | |
1063 | Output}). | |
07d83abe | 1064 | |
992a3879 AW |
1065 | @item (ice-9 ftw) |
1066 | File tree walker (@pxref{File Tree Walk}). | |
07d83abe | 1067 | |
992a3879 AW |
1068 | @item (ice-9 getopt-long) |
1069 | Command line option processing (@pxref{getopt-long}). | |
07d83abe | 1070 | |
992a3879 AW |
1071 | @item (ice-9 history) |
1072 | Refer to previous interactive expressions (@pxref{Value History}). | |
07d83abe | 1073 | |
992a3879 AW |
1074 | @item (ice-9 popen) |
1075 | Pipes to and from child processes (@pxref{Pipes}). | |
07d83abe | 1076 | |
992a3879 AW |
1077 | @item (ice-9 pretty-print) |
1078 | Nicely formatted output of Scheme expressions and objects | |
1079 | (@pxref{Pretty Printing}). | |
07d83abe | 1080 | |
992a3879 AW |
1081 | @item (ice-9 q) |
1082 | First-in first-out queues (@pxref{Queues}). | |
07d83abe | 1083 | |
992a3879 AW |
1084 | @item (ice-9 rdelim) |
1085 | Line- and character-delimited input (@pxref{Line/Delimited}). | |
07d83abe | 1086 | |
992a3879 AW |
1087 | @item (ice-9 readline) |
1088 | @code{readline} interactive command line editing (@pxref{Readline | |
1089 | Support}). | |
07d83abe | 1090 | |
992a3879 AW |
1091 | @item (ice-9 receive) |
1092 | Multiple-value handling with @code{receive} (@pxref{Multiple Values}). | |
626e36e5 | 1093 | |
992a3879 AW |
1094 | @item (ice-9 regex) |
1095 | Regular expression matching (@pxref{Regular Expressions}). | |
1096 | ||
1097 | @item (ice-9 rw) | |
1098 | Block string input/output (@pxref{Block Reading and Writing}). | |
1099 | ||
1100 | @item (ice-9 streams) | |
1101 | Sequence of values calculated on-demand (@pxref{Streams}). | |
1102 | ||
1103 | @item (ice-9 syncase) | |
1104 | R5RS @code{syntax-rules} macro system (@pxref{Syntax Rules}). | |
1105 | ||
1106 | @item (ice-9 threads) | |
1107 | Guile's support for multi threaded execution (@pxref{Scheduling}). | |
1108 | ||
1109 | @item (ice-9 documentation) | |
1110 | Online documentation (REFFIXME). | |
1111 | ||
1112 | @item (srfi srfi-1) | |
1113 | A library providing a lot of useful list and pair processing | |
1114 | procedures (@pxref{SRFI-1}). | |
1115 | ||
1116 | @item (srfi srfi-2) | |
1117 | Support for @code{and-let*} (@pxref{SRFI-2}). | |
1118 | ||
1119 | @item (srfi srfi-4) | |
1120 | Support for homogeneous numeric vectors (@pxref{SRFI-4}). | |
1121 | ||
1122 | @item (srfi srfi-6) | |
1123 | Support for some additional string port procedures (@pxref{SRFI-6}). | |
1124 | ||
1125 | @item (srfi srfi-8) | |
1126 | Multiple-value handling with @code{receive} (@pxref{SRFI-8}). | |
1127 | ||
1128 | @item (srfi srfi-9) | |
1129 | Record definition with @code{define-record-type} (@pxref{SRFI-9}). | |
1130 | ||
1131 | @item (srfi srfi-10) | |
1132 | Read hash extension @code{#,()} (@pxref{SRFI-10}). | |
1133 | ||
1134 | @item (srfi srfi-11) | |
1135 | Multiple-value handling with @code{let-values} and @code{let*-values} | |
1136 | (@pxref{SRFI-11}). | |
1137 | ||
1138 | @item (srfi srfi-13) | |
1139 | String library (@pxref{SRFI-13}). | |
1140 | ||
1141 | @item (srfi srfi-14) | |
1142 | Character-set library (@pxref{SRFI-14}). | |
1143 | ||
1144 | @item (srfi srfi-16) | |
1145 | @code{case-lambda} procedures of variable arity (@pxref{SRFI-16}). | |
1146 | ||
1147 | @item (srfi srfi-17) | |
1148 | Getter-with-setter support (@pxref{SRFI-17}). | |
1149 | ||
1150 | @item (srfi srfi-19) | |
1151 | Time/Date library (@pxref{SRFI-19}). | |
1152 | ||
1153 | @item (srfi srfi-26) | |
1154 | Convenient syntax for partial application (@pxref{SRFI-26}) | |
1155 | ||
1156 | @item (srfi srfi-31) | |
1157 | @code{rec} convenient recursive expressions (@pxref{SRFI-31}) | |
1158 | ||
1159 | @item (ice-9 slib) | |
1160 | This module contains hooks for using Aubrey Jaffer's portable Scheme | |
1161 | library SLIB from Guile (@pxref{SLIB}). | |
1162 | @end table | |
07d83abe MV |
1163 | |
1164 | ||
726b8ba3 AW |
1165 | @node provide and require |
1166 | @subsection provide and require | |
1167 | ||
1168 | Aubrey Jaffer, mostly to support his portable Scheme library SLIB, | |
1169 | implemented a provide/require mechanism for many Scheme implementations. | |
1170 | Library files in SLIB @emph{provide} a feature, and when user programs | |
1171 | @emph{require} that feature, the library file is loaded in. | |
1172 | ||
1173 | For example, the file @file{random.scm} in the SLIB package contains the | |
1174 | line | |
1175 | ||
1176 | @lisp | |
1177 | (provide 'random) | |
1178 | @end lisp | |
1179 | ||
1180 | so to use its procedures, a user would type | |
1181 | ||
1182 | @lisp | |
1183 | (require 'random) | |
1184 | @end lisp | |
1185 | ||
1186 | and they would magically become available, @emph{but still have the same | |
1187 | names!} So this method is nice, but not as good as a full-featured | |
1188 | module system. | |
1189 | ||
1190 | When SLIB is used with Guile, provide and require can be used to access | |
1191 | its facilities. | |
1192 | ||
1193 | @node Environments | |
1194 | @subsection Environments | |
1195 | @cindex environment | |
1196 | ||
1197 | Scheme, as defined in R5RS, does @emph{not} have a full module system. | |
1198 | However it does define the concept of a top-level @dfn{environment}. | |
1199 | Such an environment maps identifiers (symbols) to Scheme objects such | |
1200 | as procedures and lists: @ref{About Closure}. In other words, it | |
1201 | implements a set of @dfn{bindings}. | |
1202 | ||
1203 | Environments in R5RS can be passed as the second argument to | |
1204 | @code{eval} (@pxref{Fly Evaluation}). Three procedures are defined to | |
1205 | return environments: @code{scheme-report-environment}, | |
1206 | @code{null-environment} and @code{interaction-environment} (@pxref{Fly | |
1207 | Evaluation}). | |
1208 | ||
1209 | In addition, in Guile any module can be used as an R5RS environment, | |
1210 | i.e., passed as the second argument to @code{eval}. | |
1211 | ||
1212 | Note: the following two procedures are available only when the | |
1213 | @code{(ice-9 r5rs)} module is loaded: | |
1214 | ||
1215 | @lisp | |
1216 | (use-modules (ice-9 r5rs)) | |
1217 | @end lisp | |
1218 | ||
1219 | @deffn {Scheme Procedure} scheme-report-environment version | |
1220 | @deffnx {Scheme Procedure} null-environment version | |
1221 | @var{version} must be the exact integer `5', corresponding to revision | |
1222 | 5 of the Scheme report (the Revised^5 Report on Scheme). | |
1223 | @code{scheme-report-environment} returns a specifier for an | |
1224 | environment that is empty except for all bindings defined in the | |
1225 | report that are either required or both optional and supported by the | |
1226 | implementation. @code{null-environment} returns a specifier for an | |
1227 | environment that is empty except for the (syntactic) bindings for all | |
1228 | syntactic keywords defined in the report that are either required or | |
1229 | both optional and supported by the implementation. | |
1230 | ||
1231 | Currently Guile does not support values of @var{version} for other | |
1232 | revisions of the report. | |
1233 | ||
1234 | The effect of assigning (through the use of @code{eval}) a variable | |
1235 | bound in a @code{scheme-report-environment} (for example @code{car}) | |
1236 | is unspecified. Currently the environments specified by | |
1237 | @code{scheme-report-environment} are not immutable in Guile. | |
1238 | @end deffn | |
1239 | ||
1240 | ||
1241 | ||
07d83abe MV |
1242 | @c Local Variables: |
1243 | @c TeX-master: "guile.texi" | |
1244 | @c End: |