@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
For example, the file @file{random.scm} in the SLIB package contains the
line
-@smalllisp
+@lisp
(provide 'random)
-@end smalllisp
+@end lisp
so to use its procedures, a user would type
-@smalllisp
+@lisp
(require 'random)
-@end smalllisp
+@end lisp
and they would magically become available, @emph{but still have the same
names!} So this method is nice, but not as good as a full-featured
Note: the following two procedures are available only when the
@code{(ice-9 r5rs)} module is loaded:
-@smalllisp
+@lisp
(use-modules (ice-9 r5rs))
-@end smalllisp
+@end lisp
@deffn {Scheme Procedure} scheme-report-environment version
@deffnx {Scheme Procedure} null-environment version
In 1996 Tom Lord implemented a full-featured module system for Guile which
allows loading Scheme source files into a private name space. This system has
-been in available since at least Guile version 1.1.
+been available since at least Guile version 1.1.
For Guile version 1.5.0 and later, the system has been improved to have better
integration from C code, more fine-grained user control over interfaces, and
variation is simply to name the module, in which case its public
interface is the one accessed. For example:
-@smalllisp
+@lisp
(use-modules (ice-9 popen))
-@end smalllisp
+@end lisp
Here, the interface specification is @code{(ice-9 popen)}, and the
result is that the current module now has access to @code{open-pipe},
them to suit the current module's needs. For example:
@cindex binding renamer
-@smalllisp
+@lisp
(use-modules ((ice-9 popen)
- :select ((open-pipe . pipe-open) close-pipe)
- :renamer (symbol-prefix-proc 'unixy:)))
-@end smalllisp
+ #:select ((open-pipe . pipe-open) close-pipe)
+ #:renamer (symbol-prefix-proc 'unixy:)))
+@end lisp
Here, the interface specification is more complex than before, and the
result is that a custom interface with only two bindings is created and
open-pipe)}. Thus an alternative to the complete @code{use-modules}
statement would be
-@smalllisp
+@lisp
(define unixy:pipe-open (@@ (ice-9 popen) open-pipe))
(define unixy:close-pipe (@@ (ice-9 popen) close-pipe))
-@end smalllisp
+@end lisp
There is also @code{@@@@}, which can be used like @code{@@}, but does
not check whether the variable that is being accessed is actually
@var{spec} can also be of the form:
@cindex binding renamer
-@smalllisp
+@lisp
(MODULE-NAME [:select SELECTION] [:renamer RENAMER])
-@end smalllisp
+@end lisp
in which case a custom interface is newly created and used.
@var{module-name} is a list of symbols, as above; @var{selection} is a
@c FIXME::martin: Is this correct, and is there more to say?
-@c FIXME::martin: Define term and concept `system transformer' somewhere.
+@c FIXME::martin: Define term and concept `syntax transformer' somewhere.
@deffn syntax use-syntax module-name
-Load the module @code{module-name} and use its system
-transformer as the system transformer for the currently defined module,
-as well as installing it as the current system transformer.
+Load the module @code{module-name} and use its syntax
+transformer as the syntax transformer for the currently defined module,
+as well as installing it as the current syntax transformer.
@end deffn
@deffn syntax @@ module-name binding-name
@var{module-name} is of the form @code{(hierarchy file)}. One
example of this is
-@smalllisp
+@lisp
(define-module (ice-9 popen))
-@end smalllisp
+@end lisp
@code{define-module} makes this module available to Guile programs under
the given @var{module-name}.
The default duplicate binding resolution policy is given by the
@code{default-duplicate-binding-handler} procedure, and is
-@smalllisp
+@lisp
(replace warn-override-core warn last)
-@end smalllisp
+@end lisp
@item #:no-backtrace
@cindex no backtrace
the previous current module.
@end deffn
+@deffn {Scheme Procedure} save-module-excursion thunk
+Call @var{thunk} within a @code{dynamic-wind} such that the module that
+is current at invocation time is restored when @var{thunk}'s dynamic
+extent is left (@pxref{Dynamic Wind}).
+
+More precisely, if @var{thunk} escapes non-locally, the current module
+(at the time of escape) is saved, and the original current module (at
+the time @var{thunk}'s dynamic extent was last entered) is restored. If
+@var{thunk}'s dynamic extent is re-entered, then the current module is
+saved, and the previously saved inner module is set current again.
+@end deffn
+
@deffn {Scheme Procedure} resolve-module name
Find the module named @var{name} and return it. When it has not already
been defined, try to auto-load it. When it can't be found that way
@item (ice-9 debug)
Mikael Djurfeldt's source-level debugging support for Guile
-(@pxref{Debugging Features}).
+(@pxref{Tracing}).
@item (ice-9 expect)
Actions based on matching input from a port (@pxref{Expect}).
Read hash extension @code{#,()} (@pxref{SRFI-10}).
@item (srfi srfi-11)
-Multiple-value handling with @code{let-values} and @code{let-values*}
+Multiple-value handling with @code{let-values} and @code{let*-values}
(@pxref{SRFI-11}).
@item (srfi srfi-13)
Now fire up Guile:
-@smalllisp
+@lisp
(define bessel-lib (dynamic-link "./libbessel.so"))
(dynamic-call "init_math_bessel" bessel-lib)
(j0 2)
@result{} 0.223890779141236
-@end smalllisp
+@end lisp
The filename @file{./libbessel.so} should be pointing to the shared
library produced with the @code{gcc} command above, of course. The