@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, 2011, 2012
+@c Copyright (C) 1996, 1997, 2000-2004, 2007-2014
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
* Variables:: First-class variables.
* Module System Reflection:: First-class modules.
* Accessing Modules from C:: How to work with modules with C code.
-* Included Guile Modules:: Which modules come with Guile?
* provide and require:: The SLIB feature mechanism.
* Environments:: R5RS top-level environments.
@end menu
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
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
#:renamer (symbol-prefix-proc 'unixy:)))
@end lisp
+@noindent
+or more simply:
+
+@cindex prefix
+@lisp
+(use-modules ((ice-9 popen)
+ #:select ((open-pipe . pipe-open) close-pipe)
+ #:prefix 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
subsequently accessed by the current module. The mapping of old to new
@cindex binding renamer
@lisp
- (MODULE-NAME [#:select SELECTION] [#:renamer RENAMER])
+ (MODULE-NAME [#:select SELECTION]
+ [#:prefix PREFIX]
+ [#:renamer RENAMER])
@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
-list of selection-specs; and @var{renamer} is a procedure that takes a
-symbol and returns its new name. A selection-spec is either a symbol or
-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}
-clause is omitted, @var{renamer} operates on the used module's public
-interface.
+list of selection-specs; @var{prefix} is a symbol that is prepended to
+imported names; and @var{renamer} is a procedure that takes a symbol and
+returns its new name. A selection-spec is either a symbol or 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 modified by @var{prefix} and @var{renamer}.
+
+The @code{#:select}, @code{#:prefix}, and @code{#:renamer} clauses are
+optional. If all are omitted, the returned interface has no bindings.
+If the @code{#:select} clause is omitted, @var{prefix} and @var{renamer}
+operate on the used module's public interface.
In addition to the above, @var{spec} can also include a @code{#:version}
clause, of the form:
by using @code{define-public} or @code{export} (both documented below).
@end itemize
-@deffn syntax define-module module-name [options @dots{}]
+@deffn syntax define-module module-name option @dots{}
@var{module-name} is a list of one or more symbols.
@lisp
@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.
@table @code
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{Build Config}). For each directory 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
@lisp
(library (mylib (1 2))
- (import (otherlib (3)))
- (export mybinding))
+ (export mybinding)
+ (import (otherlib (3))))
@end lisp
is equivalent to the module definition:
@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
@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
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]
+@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
(@pxref{R6RS Version References}). The name is a list of symbols.
@end deffn
-@deffn {Scheme Procedure} resolve-interface name [#:select=#f] [#:hide='()] [#:select=()] [#:prefix=#f] [#:renamer] [#:version=#f]
+@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.
variable, always.
@example
-SCM my_eval_string (SCM str)
-@{
- static SCM eval_string_var = SCM_BOOL_F;
+static SCM eval_string_var;
- if (scm_is_false (eval_string_var))
- eval_string_var =
- scm_c_public_lookup ("ice-9 eval-string", "eval-string");
+/* 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
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}.
+@var{module_name}.
@end deftypefn
In addition, there are a number of other lookup-related procedures. We
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 @var{#f}.
+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})
interpreted as for @code{scm_c_define_module}.
@end deftypefn
-@deftypefn {C Function} SCM scm_c_export ({const char *}@var{name}, ...)
+@deftypefn {C Function} void 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 Included Guile Modules
-@subsection Included Guile Modules
-
-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}).
-
-@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).
-
-@item (srfi srfi-1)
-A library providing a lot of useful list and pair processing
-procedures (@pxref{SRFI-1}).
-
-@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
-
-
@node provide and require
@subsection provide and require
HCoop / bpt / guile.git / blobdiff