X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/626e36e5cbfb8a251c647d44116bd2b34bc88106..18e1113513467f319de09feae51e792548db9ecc:/doc/ref/api-modules.texi diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi index 709aa7312..286a37d7e 100644 --- a/doc/ref/api-modules.texi +++ b/doc/ref/api-modules.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2010 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2010, 2011, 2012, 2013 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -44,12 +44,12 @@ be used for interacting with the module system. * General Information about Modules:: Guile module basics. * Using Guile Modules:: How to use existing modules. * Creating Guile Modules:: How to package your code into modules. -* Module System Reflection:: Accessing module objects at run-time. -* Included Guile Modules:: Which modules come with Guile? +* Modules and the File System:: Installing modules in the file system. * R6RS Version References:: Using version numbers with modules. * R6RS Libraries:: The library and import forms. -* Accessing Modules from C:: How to work with modules with C code. * Variables:: First-class variables. +* Module System Reflection:: First-class modules. +* Accessing Modules from C:: How to work with modules with C code. * provide and require:: The SLIB feature mechanism. * Environments:: R5RS top-level environments. @end menu @@ -61,12 +61,6 @@ A Guile module can be thought of as a collection of named procedures, variables and macros. More precisely, it is a set of @dfn{bindings} of symbols (names) to Scheme objects. -An environment is a mapping from identifiers (or symbols) to locations, -i.e., a set of bindings. -There are top-level environments and lexical environments. -The environment in which a lambda is executed is remembered as part of its -definition. - Within a module, all bindings are visible. Certain bindings can be declared @dfn{public}, in which case they are added to the module's so-called @dfn{export list}; this set of public bindings is @@ -81,42 +75,18 @@ algorithmically @dfn{rename} bindings. In contrast, when using the providing module's public interface, the entire export list is available without renaming (@pxref{Using Guile Modules}). -To use a module, it must be found and loaded. All Guile modules have a -unique @dfn{module name}, which is a list of one or more symbols. -Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}. When Guile -searches for the code of a module, it constructs the name of the file to -load by concatenating the name elements with slashes between the -elements and appending a number of file name extensions from the list -@code{%load-extensions} (@pxref{Loading}). The resulting file name is -then searched in all directories in the variable @code{%load-path} -(@pxref{Build Config}). For example, the @code{(ice-9 popen)} module -would result in the filename @code{ice-9/popen.scm} and searched in the -installation directories of Guile and in all other directories in the -load path. - -A slightly different search mechanism is used when a client module -specifies a version reference as part of a request to load a module -(@pxref{R6RS Version References}). Instead of searching the directories -in the load path for a single filename, Guile uses the elements of the -version reference to locate matching, numbered subdirectories of a -constructed base path. For example, a request for the -@code{(rnrs base)} module with version reference @code{(6)} would cause -Guile to discover the @code{rnrs/6} subdirectory (if it exists in any of -the directories in the load path) and search its contents for the -filename @code{base.scm}. - -When multiple modules are found that match a version reference, Guile -sorts these modules by version number, followed by the length of their -version specifications, in order to choose a ``best'' match. - -@c FIXME::martin: Not sure about this, maybe someone knows better? -Every module has a so-called syntax transformer associated with it. -This is a procedure which performs all syntax transformation for the -time the module is read in and evaluated. When working with modules, -you can manipulate the current syntax transformer using the -@code{use-syntax} syntactic form or the @code{#:use-syntax} module -definition option (@pxref{Creating Guile Modules}). +All Guile modules have a unique @dfn{module name}, for example +@code{(ice-9 popen)} or @code{(srfi srfi-11)}. Module names are lists +of one or more symbols. +When Guile goes to use an interface from a module, for example +@code{(ice-9 popen)}, Guile first looks to see if it has loaded +@code{(ice-9 popen)} for any reason. If the module has not been loaded +yet, Guile searches a @dfn{load path} for a file that might define it, +and loads that file. + +The following subsections go into more detail on using, creating, +installing, and otherwise manipulating modules and the module system. @node Using Guile Modules @subsection Using Guile Modules @@ -127,8 +97,8 @@ types of access are handled by the syntactic form @code{use-modules}, 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 @code{%load-path} (@pxref{Build -Config}). +that code has not yet been loaded, following @code{%load-path} +(@pxref{Modules and the File System}). An @dfn{interface specification} has one of two forms. The first variation is simply to name the module, in which case its public @@ -140,8 +110,7 @@ interface is the one accessed. For example: Here, the interface specification is @code{(ice-9 popen)}, and the result is that the current module now has access to @code{open-pipe}, -@code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Included -Guile Modules}). +@code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Pipes}). Note in the previous example that if the current module had already defined @code{open-pipe}, that definition would be overwritten by the @@ -198,14 +167,11 @@ has not yet been loaded yet will be loaded when referenced by a You can also use the @code{@@} and @code{@@@@} syntaxes as the target of a @code{set!} when the binding refers to a variable. -@c begin (scm-doc-string "boot-9.scm" "symbol-prefix-proc") @deffn {Scheme Procedure} symbol-prefix-proc prefix-sym Return a procedure that prefixes its arg (a symbol) with @var{prefix-sym}. -@c Insert gratuitous C++ slam here. --ttn @end deffn -@c begin (scm-doc-string "boot-9.scm" "use-modules") @deffn syntax use-modules spec @dots{} Resolve each interface specification @var{spec} into an interface and arrange for these to be accessible by the current module. The return @@ -218,7 +184,7 @@ whose public interface is found and used. @cindex binding renamer @lisp - (MODULE-NAME [:select SELECTION] [:renamer RENAMER]) + (MODULE-NAME [#:select SELECTION] [#:renamer RENAMER]) @end lisp in which case a custom interface is newly created and used. @@ -229,37 +195,26 @@ a pair of symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in the used module and @var{seen} is the name in the using module. Note that @var{seen} is also passed through @var{renamer}. -The @code{:select} and @code{:renamer} clauses are optional. If both are -omitted, the returned interface has no bindings. If the @code{:select} +The @code{#:select} and @code{#:renamer} clauses are optional. If both are +omitted, the returned interface has no bindings. If the @code{#:select} clause is omitted, @var{renamer} operates on the used module's public interface. -In addition to the above, @var{spec} can also include a @code{:version} +In addition to the above, @var{spec} can also include a @code{#:version} clause, of the form: @lisp - :version VERSION-SPEC + #:version VERSION-SPEC @end lisp -where @var{version-spec} is an R6RS-compatible version reference. The -presence of this clause changes Guile's search behavior as described in -the section on module name resolution -(@pxref{General Information about Modules}). An error will be signaled -in the case in which a module with the same name has already been -loaded, if that module specifies a version and that version is not -compatible with @var{version-spec}. +where @var{version-spec} is an R6RS-compatible version reference. An +error will be signaled in the case in which a module with the same name +has already been loaded, if that module specifies a version and that +version is not compatible with @var{version-spec}. @xref{R6RS Version +References}, for more on version references. -Signal error if module name is not resolvable. -@end deffn - - -@c FIXME::martin: Is this correct, and is there more to say? -@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 syntax -transformer as the syntax transformer for the currently defined module, -as well as installing it as the current syntax transformer. +If the module name is not resolvable, @code{use-modules} will signal an +error. @end deffn @deffn syntax @@ module-name binding-name @@ -293,10 +248,8 @@ Export all bindings which should be in the public interface, either by using @code{define-public} or @code{export} (both documented below). @end itemize -@c begin (scm-doc-string "boot-9.scm" "define-module") -@deffn syntax define-module module-name [options @dots{}] -@var{module-name} is of the form @code{(hierarchy file)}. One -example of this is +@deffn syntax define-module module-name option @dots{} +@var{module-name} is a list of one or more symbols. @lisp (define-module (ice-9 popen)) @@ -305,21 +258,15 @@ example of this is @code{define-module} makes this module available to Guile programs under the given @var{module-name}. -The @var{options} are keyword/value pairs which specify more about the -defined module. The recognized options and their meaning is shown in +@var{option} @dots{} are keyword/value pairs which specify more about the +defined module. The recognized options and their meaning are shown in the following table. -@c fixme: Should we use "#:" or ":"? - @table @code @item #:use-module @var{interface-specification} Equivalent to a @code{(use-modules @var{interface-specification})} (@pxref{Using Guile Modules}). -@item #:use-syntax @var{module} -Use @var{module} when loading the currently defined module, and install -it as the syntax transformer. - @item #:autoload @var{module} @var{symbol-list} @cindex autoload Load @var{module} when any of @var{symbol-list} are accessed. For @@ -347,7 +294,7 @@ the module is used. @item #:export @var{list} @cindex export Export all identifiers in @var{list} which must be a list of symbols -or pairs of symbols. This is equivalent to @code{(export @var{list})} +or pairs of symbols. This is equivalent to @code{(export @var{list})} in the module body. @item #:re-export @var{list} @@ -357,20 +304,6 @@ symbols or pairs 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 -or pairs 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 or pairs 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 @@ -400,6 +333,9 @@ function (@pxref{Time}). Guile assumes that a user importing a module knows what she is doing, and uses @code{#:replace} for this binding rather than @code{#:export}. +A @code{#:replace} clause is equivalent to @code{(export! @var{list})} +in the module body. + The @code{#:duplicates} (see below) provides fine-grain control about duplicate binding handling on the module-user side. @@ -464,6 +400,10 @@ 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}. +If GOOPS has been loaded before the @code{#:duplicates} clause is +processed, there are additional strategies available for dealing with +generic functions. @xref{Merging Generics}, for more information. + @findex default-duplicate-binding-handler The default duplicate binding resolution policy is given by the @code{default-duplicate-binding-handler} procedure, and is @@ -472,11 +412,6 @@ The default duplicate binding resolution policy is given by the (replace warn-override-core warn last) @end lisp -@item #:no-backtrace -@cindex no backtrace -Tell Guile not to record information for procedure backtraces when -executing the procedures in this module. - @item #:pure @cindex pure module Create a @dfn{pure} module, that is a module which does not contain any @@ -486,7 +421,6 @@ do not know anything about dangerous procedures. @end table @end deffn -@c end @deffn syntax export variable @dots{} Add all @var{variable}s (which must be symbols or pairs of symbols) to @@ -496,11 +430,9 @@ current module and its @code{cdr} specifies a name for the binding in the current module's public interface. @end deffn -@c begin (scm-doc-string "boot-9.scm" "define-public") @deffn syntax define-public @dots{} Equivalent to @code{(begin (define foo ...) (export foo))}. @end deffn -@c end @deffn syntax re-export variable @dots{} Add all @var{variable}s (which must be symbols or pairs of symbols) to @@ -509,179 +441,47 @@ symbols are handled as in @code{export}. Re-exported bindings must be imported by the current module from some other module. @end deffn -@node Module System Reflection -@subsection Module System Reflection - -The previous sections have described a declarative view of the module -system. You can also work with it programmatically by accessing and -modifying various parts of the Scheme objects that Guile uses to -implement the module system. - -At any time, there is a @dfn{current module}. This module is the one -where a top-level @code{define} and similar syntax will add new -bindings. You can find other module objects with @code{resolve-module}, -for example. - -These module objects can be used as the second argument to @code{eval}. - -@deffn {Scheme Procedure} current-module -Return the current module object. -@end deffn - -@deffn {Scheme Procedure} set-current-module module -Set the current module to @var{module} and return -the previous current module. +@deffn syntax export! variable @dots{} +Like @code{export}, but marking the exported variables as replacing. +Using a module with replacing bindings will cause any existing bindings +to be replaced without issuing any warnings. See the discussion of +@code{#:replace} above. @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 -either, create an empty module. The name is a list of symbols. -@end deffn - -@deffn {Scheme Procedure} resolve-interface name -Find the module named @var{name} as with @code{resolve-module} and -return its interface. The interface of a module is also a module -object, but it contains only the exported bindings. -@end deffn - -@deffn {Scheme Procedure} module-use! module interface -Add @var{interface} to the front of the use-list of @var{module}. Both -arguments should be module objects, and @var{interface} should very -likely be a module returned by @code{resolve-interface}. -@end deffn - - -@node Included Guile Modules -@subsection Included Guile Modules - -@c FIXME::martin: Review me! - -Some modules are included in the Guile distribution; here are references -to the entries in this manual which describe them in more detail: - -@table @strong -@item boot-9 -boot-9 is Guile's initialization module, and it is always loaded when -Guile starts up. - -@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}). +@node Modules and the File System +@subsection Modules and the File System -@item (ice-9 streams) -Sequence of values calculated on-demand (@pxref{Streams}). +Typical programs only use a small subset of modules installed on a Guile +system. In order to keep startup time down, Guile only loads modules +when a program uses them, on demand. -@item (ice-9 syncase) -R5RS @code{syntax-rules} macro system (@pxref{Syntax Rules}). +When a program evaluates @code{(use-modules (ice-9 popen))}, and the +module is not loaded, Guile searches for a conventionally-named file +from in the @dfn{load path}. -@item (ice-9 threads) -Guile's support for multi threaded execution (@pxref{Scheduling}). +In this case, loading @code{(ice-9 popen)} will eventually cause Guile +to run @code{(primitive-load-path "ice-9/popen")}. +@code{primitive-load-path} will search for a file @file{ice-9/popen} in +the @code{%load-path} (@pxref{Load Paths}). For each directory in +@code{%load-path}, Guile will try to find the file name, concatenated +with the extensions from @code{%load-extensions}. By default, this will +cause Guile to @code{stat} @file{ice-9/popen.scm}, and then +@file{ice-9/popen}. @xref{Load Paths}, for more on +@code{primitive-load-path}. -@item (ice-9 documentation) -Online documentation (REFFIXME). +If a corresponding compiled @file{.go} file is found in the +@code{%load-compiled-path} or in the fallback path, and is as fresh as +the source file, it will be loaded instead of the source file. If no +compiled file is found, Guile may try to compile the source file and +cache away the resulting @file{.go} file. @xref{Compilation}, for more +on compilation. -@item (srfi srfi-1) -A library providing a lot of useful list and pair processing -procedures (@pxref{SRFI-1}). +Once Guile finds a suitable source or compiled file is found, the file +will be loaded. If, after loading the file, the module under +consideration is still not defined, Guile will signal an error. -@item (srfi srfi-2) -Support for @code{and-let*} (@pxref{SRFI-2}). - -@item (srfi srfi-4) -Support for homogeneous numeric vectors (@pxref{SRFI-4}). - -@item (srfi srfi-6) -Support for some additional string port procedures (@pxref{SRFI-6}). - -@item (srfi srfi-8) -Multiple-value handling with @code{receive} (@pxref{SRFI-8}). - -@item (srfi srfi-9) -Record definition with @code{define-record-type} (@pxref{SRFI-9}). - -@item (srfi srfi-10) -Read hash extension @code{#,()} (@pxref{SRFI-10}). - -@item (srfi srfi-11) -Multiple-value handling with @code{let-values} and @code{let*-values} -(@pxref{SRFI-11}). - -@item (srfi srfi-13) -String library (@pxref{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}). -@end table +For more information on where and how to install Scheme modules, +@xref{Installing Site Packages}. @node R6RS Version References @@ -808,7 +608,7 @@ as a mechanism by which a library author can indicate that a particular library import should take place at a particular phase with respect to the lifecycle of the importing library. -Guile's libraries implementation uses a technique called +Guile's library implementation uses a technique called @dfn{implicit phasing} (first described by Abdulaziz Ghuloum and R. Kent Dybvig), which allows the expander and compiler to automatically determine the necessary visibility of a binding imported from another @@ -905,104 +705,6 @@ same form as in the @code{library} form described above. @end deffn -@node Accessing Modules from C -@subsection Accessing Modules from C - -The last sections have described how modules are used in Scheme code, -which is the recommended way of creating and accessing modules. You -can also work with modules from C, but it is more cumbersome. - -The following procedures are available. - -@deftypefn {C Procedure} SCM scm_current_module () -Return the module that is the @emph{current module}. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_set_current_module (SCM @var{module}) -Set the current module to @var{module} and return the previous current -module. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data}) -Call @var{func} and make @var{module} the current module during the -call. The argument @var{data} is passed to @var{func}. The return -value of @code{scm_c_call_with_current_module} is the return value of -@var{func}. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_c_lookup (const char *@var{name}) -Return the variable bound to the symbol indicated by @var{name} in the -current module. If there is no such binding or the symbol is not -bound to a variable, signal an error. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_lookup (SCM @var{name}) -Like @code{scm_c_lookup}, but the symbol is specified directly. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_c_module_lookup (SCM @var{module}, const char *@var{name}) -@deftypefnx {C Procedure} SCM scm_module_lookup (SCM @var{module}, SCM @var{name}) -Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified -module is used instead of the current one. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_c_define (const char *@var{name}, SCM @var{val}) -Bind the symbol indicated by @var{name} to a variable in the current -module and set that variable to @var{val}. When @var{name} is already -bound to a variable, use that. Else create a new variable. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_define (SCM @var{name}, SCM @var{val}) -Like @code{scm_c_define}, but the symbol is specified directly. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_c_module_define (SCM @var{module}, const char *@var{name}, SCM @var{val}) -@deftypefnx {C Procedure} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val}) -Like @code{scm_c_define} and @code{scm_define}, but the specified -module is used instead of the current one. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable}) -Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @var{#f}. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_c_define_module (const char *@var{name}, void (*@var{init})(void *), void *@var{data}) -Define a new module named @var{name} and make it current while -@var{init} is called, passing it @var{data}. Return the module. - -The parameter @var{name} is a string with the symbols that make up -the module name, separated by spaces. For example, @samp{"foo bar"} names -the module @samp{(foo bar)}. - -When there already exists a module named @var{name}, it is used -unchanged, otherwise, an empty module is created. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_c_resolve_module (const char *@var{name}) -Find the module name @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 either, create an empty module. The name is interpreted as -for @code{scm_c_define_module}. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_resolve_module (SCM @var{name}) -Like @code{scm_c_resolve_module}, but the name is given as a real list -of symbols. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_c_use_module (const char *@var{name}) -Add the module named @var{name} to the uses list of the current -module, as with @code{(use-modules @var{name})}. The name is -interpreted as for @code{scm_c_define_module}. -@end deftypefn - -@deftypefn {C Procedure} SCM scm_c_export (const char *@var{name}, ...) -Add the bindings designated by @var{name}, ... to the public interface -of the current module. The list of names is terminated by -@code{NULL}. -@end deftypefn - - @node Variables @subsection Variables @tpindex Variables @@ -1019,9 +721,8 @@ including for example @code{#f}); otherwise the variable is On its own, a variable object is anonymous. A variable is said to be @dfn{bound} when it is associated with a name in some way, usually a -symbol in a module obarray. When this happens, the relationship is -mutual: the variable is bound to the name (in that module), and the name -(in that module) is bound to the variable. +symbol in a module obarray. When this happens, the name is said to be +bound to the variable, in that module. (That's the theory, anyway. In practice, defined-ness and bound-ness sometimes get confused, because Lisp and Scheme implementations have @@ -1056,8 +757,8 @@ Return a variable initialized to value @var{init}. @deffn {Scheme Procedure} variable-bound? var @deffnx {C Function} scm_variable_bound_p (var) -Return @code{#t} iff @var{var} is bound to a value. -Throws an error if @var{var} is not a variable object. +Return @code{#t} if @var{var} is bound to a value, or @code{#f} +otherwise. Throws an error if @var{var} is not a variable object. @end deffn @deffn {Scheme Procedure} variable-ref var @@ -1081,10 +782,283 @@ Unset the value of the variable @var{var}, leaving @var{var} unbound. @deffn {Scheme Procedure} variable? obj @deffnx {C Function} scm_variable_p (obj) -Return @code{#t} iff @var{obj} is a variable object, else -return @code{#f}. +Return @code{#t} if @var{obj} is a variable object, else return +@code{#f}. +@end deffn + + +@node Module System Reflection +@subsection Module System Reflection + +The previous sections have described a declarative view of the module +system. You can also work with it programmatically by accessing and +modifying various parts of the Scheme objects that Guile uses to +implement the module system. + +At any time, there is a @dfn{current module}. This module is the one +where a top-level @code{define} and similar syntax will add new +bindings. You can find other module objects with @code{resolve-module}, +for example. + +These module objects can be used as the second argument to @code{eval}. + +@deffn {Scheme Procedure} current-module +@deffnx {C Function} scm_current_module () +Return the current module object. +@end deffn + +@deffn {Scheme Procedure} set-current-module module +@deffnx {C Function} scm_set_current_module (module) +Set the current module to @var{module} and return +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 [autoload=#t] [version=#f] @ + [#:ensure=#t] +@deffnx {C Function} scm_resolve_module (name) +Find the module named @var{name} and return it. When it has not already +been defined and @var{autoload} is true, try to auto-load it. When it +can't be found that way either, create an empty module if @var{ensure} +is true, otherwise return @code{#f}. If @var{version} is true, ensure +that the resulting module is compatible with the given version reference +(@pxref{R6RS Version References}). The name is a list of symbols. +@end deffn + +@deffn {Scheme Procedure} resolve-interface name [#:select=#f] @ + [#:hide='()] [#:prefix=#f] @ + [#:renamer=#f] [#:version=#f] +Find the module named @var{name} as with @code{resolve-module} and +return its interface. The interface of a module is also a module +object, but it contains only the exported bindings. +@end deffn + +@deffn {Scheme Procedure} module-uses module +Return a list of the interfaces used by @var{module}. +@end deffn + +@deffn {Scheme Procedure} module-use! module interface +Add @var{interface} to the front of the use-list of @var{module}. Both +arguments should be module objects, and @var{interface} should very +likely be a module returned by @code{resolve-interface}. +@end deffn + +@deffn {Scheme Procedure} reload-module module +Revisit the source file that corresponds to @var{module}. Raises an +error if no source file is associated with the given module. +@end deffn + +As mentioned in the previous section, modules contain a mapping between +identifiers (as symbols) and storage locations (as variables). Guile +defines a number of procedures to allow access to this mapping. If you +are programming in C, @ref{Accessing Modules from C}. + +@deffn {Scheme Procedure} module-variable module name +Return the variable bound to @var{name} (a symbol) in @var{module}, or +@code{#f} if @var{name} is unbound. +@end deffn + +@deffn {Scheme Procedure} module-add! module name var +Define a new binding between @var{name} (a symbol) and @var{var} (a +variable) in @var{module}. +@end deffn + +@deffn {Scheme Procedure} module-ref module name +Look up the value bound to @var{name} in @var{module}. Like +@code{module-variable}, but also does a @code{variable-ref} on the +resulting variable, raising an error if @var{name} is unbound. +@end deffn + +@deffn {Scheme Procedure} module-define! module name value +Locally bind @var{name} to @var{value} in @var{module}. If @var{name} +was already locally bound in @var{module}, i.e., defined locally and not +by an imported module, the value stored in the existing variable will be +updated. Otherwise, a new variable will be added to the module, via +@code{module-add!}. +@end deffn + +@deffn {Scheme Procedure} module-set! module name value +Update the binding of @var{name} in @var{module} to @var{value}, raising +an error if @var{name} is not already bound in @var{module}. +@end deffn + +There are many other reflective procedures available in the default +environment. If you find yourself using one of them, please contact the +Guile developers so that we can commit to stability for that interface. + + +@node Accessing Modules from C +@subsection Accessing Modules from C + +The last sections have described how modules are used in Scheme code, +which is the recommended way of creating and accessing modules. You +can also work with modules from C, but it is more cumbersome. + +The following procedures are available. + +@deftypefn {C Function} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data}) +Call @var{func} and make @var{module} the current module during the +call. The argument @var{data} is passed to @var{func}. The return +value of @code{scm_c_call_with_current_module} is the return value of +@var{func}. +@end deftypefn + +@deftypefn {C Function} SCM scm_public_variable (SCM @var{module_name}, SCM @var{name}) +@deftypefnx {C Function} SCM scm_c_public_variable ({const char *}@var{module_name}, {const char *}@var{name}) +Find a the variable bound to the symbol @var{name} in the public +interface of the module named @var{module_name}. + +@var{module_name} should be a list of symbols, when represented as a +Scheme object, or a space-separated string, in the @code{const char *} +case. See @code{scm_c_define_module} below, for more examples. + +Signals an error if no module was found with the given name. If +@var{name} is not bound in the module, just returns @code{#f}. +@end deftypefn + +@deftypefn {C Function} SCM scm_private_variable (SCM @var{module_name}, SCM @var{name}) +@deftypefnx {C Function} SCM scm_c_private_variable ({const char *}@var{module_name}, {const char *}@var{name}) +Like @code{scm_public_variable}, but looks in the internals of the +module named @var{module_name} instead of the public interface. +Logically, these procedures should only be called on modules you write. +@end deftypefn + +@deftypefn {C Function} SCM scm_public_lookup (SCM @var{module_name}, SCM @var{name}) +@deftypefnx {C Function} SCM scm_c_public_lookup ({const char *}@var{module_name}, {const char *}@var{name}) +@deftypefnx {C Function} SCM scm_private_lookup (SCM @var{module_name}, SCM @var{name}) +@deftypefnx {C Function} SCM scm_c_private_lookup ({const char *}@var{module_name}, {const char *}@var{name}) +Like @code{scm_public_variable} or @code{scm_private_variable}, but if +the @var{name} is not bound in the module, signals an error. Returns a +variable, always. + +@example +static SCM eval_string_var; + +/* NOTE: It is important that the call to 'my_init' + happens-before all calls to 'my_eval_string'. */ +void my_init (void) +@{ + eval_string_var = scm_c_public_lookup ("ice-9 eval-string", + "eval-string"); +@} + +SCM my_eval_string (SCM str) +@{ + return scm_call_1 (scm_variable_ref (eval_string_var), str); +@} +@end example +@end deftypefn + +@deftypefn {C Function} SCM scm_public_ref (SCM @var{module_name}, SCM @var{name}) +@deftypefnx {C Function} SCM scm_c_public_ref ({const char *}@var{module_name}, {const char *}@var{name}) +@deftypefnx {C Function} SCM scm_private_ref (SCM @var{module_name}, SCM @var{name}) +@deftypefnx {C Function} SCM scm_c_private_ref ({const char *}@var{module_name}, {const char *}@var{name}) +Like @code{scm_public_lookup} or @code{scm_private_lookup}, but +additionally dereferences the variable. If the variable object is +unbound, signals an error. Returns the value bound to @var{name} in +@var{module_name}. +@end deftypefn + +In addition, there are a number of other lookup-related procedures. We +suggest that you use the @code{scm_public_} and @code{scm_private_} +family of procedures instead, if possible. + +@deftypefn {C Function} SCM scm_c_lookup ({const char *}@var{name}) +Return the variable bound to the symbol indicated by @var{name} in the +current module. If there is no such binding or the symbol is not +bound to a variable, signal an error. +@end deftypefn + +@deftypefn {C Function} SCM scm_lookup (SCM @var{name}) +Like @code{scm_c_lookup}, but the symbol is specified directly. +@end deftypefn + +@deftypefn {C Function} SCM scm_c_module_lookup (SCM @var{module}, {const char *}@var{name}) +@deftypefnx {C Function} SCM scm_module_lookup (SCM @var{module}, SCM @var{name}) +Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified +module is used instead of the current one. +@end deftypefn + +@deftypefn {C Function} SCM scm_module_variable (SCM @var{module}, SCM @var{name}) +Like @code{scm_module_lookup}, but if the binding does not exist, just +returns @code{#f} instead of raising an error. +@end deftypefn + +To define a value, use @code{scm_define}: + +@deftypefn {C Function} SCM scm_c_define ({const char *}@var{name}, SCM @var{val}) +Bind the symbol indicated by @var{name} to a variable in the current +module and set that variable to @var{val}. When @var{name} is already +bound to a variable, use that. Else create a new variable. +@end deftypefn + +@deftypefn {C Function} SCM scm_define (SCM @var{name}, SCM @var{val}) +Like @code{scm_c_define}, but the symbol is specified directly. +@end deftypefn + +@deftypefn {C Function} SCM scm_c_module_define (SCM @var{module}, {const char *}@var{name}, SCM @var{val}) +@deftypefnx {C Function} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val}) +Like @code{scm_c_define} and @code{scm_define}, but the specified +module is used instead of the current one. +@end deftypefn + +In some rare cases, you may need to access the variable that +@code{scm_module_define} would have accessed, without changing the +binding of the existing variable, if one is present. In that case, use +@code{scm_module_ensure_local_variable}: + +@deftypefn {C Function} SCM scm_module_ensure_local_variable (SCM @var{module}, SCM @var{sym}) +Like @code{scm_module_define}, but if the @var{sym} is already locally +bound in that module, the variable's existing binding is not reset. +Returns a variable. +@end deftypefn + +@deftypefn {C Function} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable}) +Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @code{#f}. +@end deftypefn + +@deftypefn {C Function} SCM scm_c_define_module ({const char *}@var{name}, void (*@var{init})(void *), void *@var{data}) +Define a new module named @var{name} and make it current while +@var{init} is called, passing it @var{data}. Return the module. + +The parameter @var{name} is a string with the symbols that make up +the module name, separated by spaces. For example, @samp{"foo bar"} names +the module @samp{(foo bar)}. + +When there already exists a module named @var{name}, it is used +unchanged, otherwise, an empty module is created. +@end deftypefn + +@deftypefn {C Function} SCM scm_c_resolve_module ({const char *}@var{name}) +Find the module name @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 either, create an empty module. The name is interpreted as +for @code{scm_c_define_module}. +@end deftypefn + +@deftypefn {C Function} SCM scm_c_use_module ({const char *}@var{name}) +Add the module named @var{name} to the uses list of the current +module, as with @code{(use-modules @var{name})}. The name is +interpreted as for @code{scm_c_define_module}. +@end deftypefn + +@deftypefn {C Function} SCM scm_c_export ({const char *}@var{name}, ...) +Add the bindings designated by @var{name}, ... to the public interface +of the current module. The list of names is terminated by +@code{NULL}. +@end deftypefn + @node provide and require @subsection provide and require