@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
which accepts one or more interface specifications and, upon evaluation,
arranges for those interfaces to be available to the current module.
This process may include locating and loading code for a given module if
-that code has not yet been loaded, following %load-path (@pxref{Build
+that code has not yet been loaded, following @code{%load-path} (@pxref{Build
Config}).
An @dfn{interface specification} has one of two forms. The first
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},
module to be accessed, but also selects bindings from it and renames
them to suit the current module's needs. For example:
-@smalllisp
+@cindex binding renamer
+@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:
-@smalllisp
+@cindex binding renamer
+@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}.
Use @var{module} when loading the currently defined module, and install
it as the syntax transformer.
-@item #:autoload @var{module} @var{symbol}
+@item #:autoload @var{module} @var{symbol-list}
@cindex autoload
-Load @var{module} whenever @var{symbol} is accessed.
+Load @var{module} when any of @var{symbol-list} are accessed. For
+example,
+
+@example
+(define-module (my mod)
+ #:autoload (srfi srfi-1) (partition delete-duplicates))
+...
+(if something
+ (set! foo (delete-duplicates ...)))
+@end example
+
+When a module is autoloaded, all its bindings become available.
+@var{symbol-list} is just those that will first trigger the load.
+
+An autoload is a good way to put off loading a big module until it's
+really needed, for instance for faster startup or if it will only be
+needed in certain circumstances.
+
+@code{@@} can do a similar thing (@pxref{Using Guile Modules}), but in
+that case an @code{@@} form must be written every time a binding from
+the module is used.
@item #:export @var{list}
@cindex export
-Export all identifiers in @var{list}, which must be a list of symbols.
+Export all identifiers in @var{list} which must be a list of symbols.
This is equivalent to @code{(export @var{list})} in the module body.
+@item #:re-export @var{list}
+@cindex re-export
+Re-export all identifiers in @var{list} which must be a list of
+symbols. The symbols in @var{list} must be imported by the current
+module from other modules. This is equivalent to @code{re-export}
+below.
+
+@item #:export-syntax @var{list}
+@cindex export-syntax
+Export all identifiers in @var{list} which must be a list of symbols.
+The identifiers in @var{list} must refer to macros (@pxref{Macros})
+defined in the current module. This is equivalent to
+@code{(export-syntax @var{list})} in the module body.
+
+@item #:re-export-syntax @var{list}
+@cindex re-export-syntax
+Re-export all identifiers in @var{list} which must be a list of
+symbols. The symbols in @var{list} must refer to macros imported by
+the current module from other modules. This is equivalent to
+@code{(re-export-syntax @var{list})} in the module body.
+
+@item #:replace @var{list}
+@cindex replace
+@cindex replacing binding
+@cindex overriding binding
+@cindex duplicate binding
+Export all identifiers in @var{list} (a list of symbols) and mark them
+as @dfn{replacing bindings}. In the module user's name space, this
+will have the effect of replacing any binding with the same name that
+is not also ``replacing''. Normally a replacement results in an
+``override'' warning message, @code{#:replace} avoids that.
+
+This is useful for modules that export bindings that have the same
+name as core bindings. @code{#:replace}, in a sense, lets Guile know
+that the module @emph{purposefully} replaces a core binding. It is
+important to note, however, that this binding replacement is confined
+to the name space of the module user. In other words, the value of the
+core binding in question remains unchanged for other modules.
+
+For instance, SRFI-39 exports a binding named
+@code{current-input-port} (@pxref{SRFI-39}) that is a function which
+is upwardly compatible with the core @code{current-input-port}
+function. Therefore, SRFI-39 exports its version with
+@code{#:replace}.
+
+SRFI-19, on the other hand, exports its own version of
+@code{current-time} (@pxref{SRFI-19 Time}) which is not compatible
+with the core @code{current-time} function (@pxref{Time}). Therefore,
+SRFI-19 does not use @code{#:replace}.
+
+The @code{#:replace} option can also be used by a module which is
+intentionally producing a new special kind of environment and should
+override any core or other bindings already in scope. For example
+perhaps a logic processing environment where @code{<=} is an inference
+instead of a comparison.
+
+The @code{#:duplicates} (see below) provides fine-grain control about
+duplicate binding handling on the module-user side.
+
+@item #:duplicates @var{list}
+@cindex duplicate binding handlers
+@cindex duplicate binding
+@cindex overriding binding
+Tell Guile to handle duplicate bindings for the bindings imported by
+the current module according to the policy defined by @var{list}, a
+list of symbols. @var{list} must contain symbols representing a
+duplicate binding handling policy chosen among the following:
+
+@table @code
+@item check
+Raises an error when a binding is imported from more than one place.
+@item warn
+Issue a warning when a binding is imported from more than one place
+and leave the responsibility of actually handling the duplication to
+the next duplicate binding handler.
+@item replace
+When a new binding is imported that has the same name as a previously
+imported binding, then do the following:
+
+@enumerate
+@item
+@cindex replacing binding
+If the old binding was said to be @dfn{replacing} (via the
+@code{#:replace} option above) and the new binding is not replacing,
+the keep the old binding.
+@item
+If the old binding was not said to be replacing and the new binding is
+replacing, then replace the old binding with the new one.
+@item
+If neither the old nor the new binding is replacing, then keep the old
+one.
+@end enumerate
+
+@item warn-override-core
+Issue a warning when a core binding is being overwritten and actually
+override the core binding with the new one.
+@item first
+In case of duplicate bindings, the firstly imported binding is always
+the one which is kept.
+@item last
+In case of duplicate bindings, the lastly imported binding is always
+the one which is kept.
+@item noop
+In case of duplicate bindings, leave the responsibility to the next
+duplicate handler.
+@end table
+
+If @var{list} contains more than one symbol, then the duplicate
+binding handlers which appear first will be used first when resolving
+a duplicate binding situation. As mentioned above, some resolution
+policies may explicitly leave the responsibility of handling the
+duplication to the next handler in @var{list}.
+
+@findex default-duplicate-binding-handler
+The default duplicate binding resolution policy is given by the
+@code{default-duplicate-binding-handler} procedure, and is
+
+@lisp
+(replace warn-override-core warn last)
+@end lisp
+
@item #:no-backtrace
@cindex no backtrace
Tell Guile not to record information for procedure backtraces when
@end deffn
@c end
+@deffn syntax re-export variable @dots{}
+Add all @var{variable}s (which must be symbols) to the list of
+re-exported bindings of the current module. Re-exported bindings must
+be imported by the current module from some other module.
+@end deffn
+
@node Module System Reflection
@subsubsection Module System Reflection
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 threads)
-Guile's support for multi threaded execution (@pxref{Scheduling}).
+@item (ice-9 expect)
+Actions based on matching input from a port (@pxref{Expect}).
+
+@item (ice-9 format)
+Formatted output in the style of Common Lisp (@pxref{Formatted
+Output}).
+
+@item (ice-9 ftw)
+File tree walker (@pxref{File Tree Walk}).
+
+@item (ice-9 getopt-long)
+Command line option processing (@pxref{getopt-long}).
+
+@item (ice-9 history)
+Refer to previous interactive expressions (@pxref{Value History}).
+
+@item (ice-9 popen)
+Pipes to and from child processes (@pxref{Pipes}).
+
+@item (ice-9 pretty-print)
+Nicely formatted output of Scheme expressions and objects
+(@pxref{Pretty Printing}).
+
+@item (ice-9 q)
+First-in first-out queues (@pxref{Queues}).
@item (ice-9 rdelim)
Line- and character-delimited input (@pxref{Line/Delimited}).
+@item (ice-9 readline)
+@code{readline} interactive command line editing (@pxref{Readline
+Support}).
+
+@item (ice-9 receive)
+Multiple-value handling with @code{receive} (@pxref{Multiple Values}).
+
+@item (ice-9 regex)
+Regular expression matching (@pxref{Regular Expressions}).
+
@item (ice-9 rw)
Block string input/output (@pxref{Block Reading and Writing}).
+@item (ice-9 streams)
+Sequence of values calculated on-demand (@pxref{Streams}).
+
+@item (ice-9 syncase)
+R5RS @code{syntax-rules} macro system (@pxref{Syntax Rules}).
+
+@item (ice-9 threads)
+Guile's support for multi threaded execution (@pxref{Scheduling}).
+
@item (ice-9 documentation)
Online documentation (REFFIXME).
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)
@item (srfi srfi-14)
Character-set library (@pxref{SRFI-14}).
+@item (srfi srfi-16)
+@code{case-lambda} procedures of variable arity (@pxref{SRFI-16}).
+
@item (srfi srfi-17)
Getter-with-setter support (@pxref{SRFI-17}).
+@item (srfi srfi-19)
+Time/Date library (@pxref{SRFI-19}).
+
@item (srfi srfi-26)
Convenient syntax for partial application (@pxref{SRFI-26})
+@item (srfi srfi-31)
+@code{rec} convenient recursive expressions (@pxref{SRFI-31})
+
@item (ice-9 slib)
This module contains hooks for using Aubrey Jaffer's portable Scheme
library SLIB from Guile (@pxref{SLIB}).
-
-@c FIXME::martin: This module is not in the distribution. Remove it
-@c from here?
-@item (ice-9 jacal)
-This module contains hooks for using Aubrey Jaffer's symbolic math
-package Jacal from Guile (@pxref{JACAL}).
@end table
integrates dynamically linked libraries into the module system.
@menu
-* Low level dynamic linking::
-* Compiled Code Modules::
-* Dynamic Linking and Compiled Code Modules::
+* Low level dynamic linking::
+* Compiled Code Modules::
+* Dynamic Linking and Compiled Code Modules::
+* Compiled Code Installation::
@end menu
@node Low level dynamic linking
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
@end lisp
@end deffn
+
+@node Compiled Code Installation
+@subsubsection Compiled Code Installation
+
+The simplest way to write a module using compiled C code is
+
+@example
+(define-module (foo bar))
+(load-extension "foobar-c-code" "foo_bar_init")
+@end example
+
+When loaded with @code{(use-modules (foo bar))}, the
+@code{load-extension} call looks for the @file{foobar-c-code.so} (etc)
+object file in the standard system locations, such as @file{/usr/lib}
+or @file{/usr/local/lib}.
+
+If someone installs your module to a non-standard location then the
+object file won't be found. You can address this by inserting the
+install location in the @file{foo/bar.scm} file. This is convenient
+for the user and also guarantees the intended object is read, even if
+stray older or newer versions are in the loader's path.
+
+The usual way to specify an install location is with a @code{prefix}
+at the configure stage, for instance @samp{./configure prefix=/opt}
+results in library files as say @file{/opt/lib/foobar-c-code.so}.
+When using Autoconf (@pxref{Top, , Introduction, autoconf, The GNU
+Autoconf Manual}), the library location is in a @code{libdir}
+variable. Its value is intended to be expanded by @command{make}, and
+can by substituted into a source file like @file{foo.scm.in}
+
+@example
+(define-module (foo bar))
+(load-extension "XXlibdirXX/foobar-c-code" "foo_bar_init")
+@end example
+
+@noindent
+with the following in a @file{Makefile}, using @command{sed}
+(@pxref{Top, , Introduction, sed, SED, A Stream Editor}),
+
+@example
+foo.scm: foo.scm.in
+ sed 's|XXlibdirXX|$(libdir)|' <foo.scm.in >foo.scm
+@end example
+
+The actual pattern @code{XXlibdirXX} is arbitrary, it's only something
+which doesn't otherwise occur. If several modules need the value, it
+can be easier to create one @file{foo/config.scm} with a define of the
+@code{libdir} location, and use that as required.
+
+@example
+(define-module (foo config))
+(define-public foo-config-libdir "XXlibdirXX"")
+@end example
+
+Such a file might have other locations too, for instance a data
+directory for auxiliary files, or @code{localedir} if the module has
+its own @code{gettext} message catalogue
+(@pxref{Internationalization}).
+
+When installing multiple C code objects, it can be convenient to put
+them in a subdirectory of @code{libdir}, thus giving for example
+@code{/usr/lib/foo/some-obj.so}. If the objects are only meant to be
+used through the module, then a subdirectory keeps them out of sight.
+
+It will be noted all of the above requires that the Scheme code to be
+found in @code{%load-path} (@pxref{Build Config}). Presently it's
+left up to the system administrator or each user to augment that path
+when installing Guile modules in non-default locations. But having
+reached the Scheme code, that code should take care of hitting any of
+its own private files etc.
+
+Presently there's no convention for having a Guile version number in
+module C code filenames or directories. This is primarily because
+there's no established principles for two versions of Guile to be
+installed under the same prefix (eg. two both under @file{/usr}).
+Assuming upward compatibility is maintained then this should be
+unnecessary, and if compatibility is not maintained then it's highly
+likely a package will need to be revisited anyway.
+
+The present suggestion is that modules should assume when they're
+installed under a particular @code{prefix} that there's a single
+version of Guile there, and the @code{guile-config} at build time has
+the necessary information about it. C code or Scheme code might adapt
+itself accordingly (allowing for features not available in an older
+version for instance).
+
+
@node Variables
@subsection Variables
@tpindex Variables
HCoop / bpt / guile.git / blobdiff