[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
guile/guile-core/doc ChangeLog scheme-io.texi s...
From: |
Martin Grabmueller |
Subject: |
guile/guile-core/doc ChangeLog scheme-io.texi s... |
Date: |
Wed, 02 May 2001 07:44:39 -0700 |
CVSROOT: /cvs
Module name: guile
Changes by: Martin Grabmueller <address@hidden> 01/05/02 07:44:39
Modified files:
guile-core/doc : ChangeLog scheme-io.texi scheme-modules.texi
Log message:
* scheme-modules.texi (Dynamic Libraries): Renamed from `Dynamic
Linking from Marius''.
(The Guile module system): Removed obsolete naming convention.
(Loading Guile Modules, Creating Guile Modules),
(More Module Procedures, Included Guile Modules): New nodes, split
from `The Guile module system'.
(The Guile module system): Changed references to (ice-9 slib) to
(ice-9 popen), because note everybody has SLIB installed.
(Included Guile Modules): Added a bunch of modules shipped with
Guile.
(Dynamic Libraries): (old version) Removed.
* scheme-io.texi (Block Reading and Writing): Corrected
capitalization, so it builds again.
CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/ChangeLog.diff?cvsroot=OldCVS&tr1=1.77&tr2=1.78&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/scheme-io.texi.diff?cvsroot=OldCVS&tr1=1.10&tr2=1.11&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/scheme-modules.texi.diff?cvsroot=OldCVS&tr1=1.5&tr2=1.6&r1=text&r2=text
Patches:
Index: guile/guile-core/doc/ChangeLog
diff -u guile/guile-core/doc/ChangeLog:1.77 guile/guile-core/doc/ChangeLog:1.78
--- guile/guile-core/doc/ChangeLog:1.77 Tue May 1 14:05:44 2001
+++ guile/guile-core/doc/ChangeLog Wed May 2 07:44:38 2001
@@ -1,3 +1,21 @@
+2001-05-02 Martin Grabmueller <address@hidden>
+
+ * scheme-modules.texi (Dynamic Libraries): Renamed from `Dynamic
+ Linking from Marius''.
+ (The Guile module system): Removed obsolete naming convention.
+ (Loading Guile Modules, Creating Guile Modules),
+ (More Module Procedures, Included Guile Modules): New nodes, split
+ from `The Guile module system'.
+ (The Guile module system): Changed references to (ice-9 slib) to
+ (ice-9 popen), because note everybody has SLIB installed.
+ (Included Guile Modules): Added a bunch of modules shipped with
+ Guile.
+
+ (Dynamic Libraries): (old version) Removed.
+
+ * scheme-io.texi (Block Reading and Writing): Corrected
+ capitalization, so it builds again.
+
2001-05-01 Gary Houston <address@hidden>
* scheme-io.texi: Removed obsolete section Binary IO. Added
Index: guile/guile-core/doc/scheme-io.texi
diff -u guile/guile-core/doc/scheme-io.texi:1.10
guile/guile-core/doc/scheme-io.texi:1.11
--- guile/guile-core/doc/scheme-io.texi:1.10 Tue May 1 14:05:44 2001
+++ guile/guile-core/doc/scheme-io.texi Wed May 2 07:44:38 2001
@@ -429,7 +429,7 @@
@code{(#<eof> . #<eof>)}.
@end deffn
address@hidden Block reading and writing
address@hidden Block Reading and Writing
@section Block reading and writing
The Block-string-I/O module can be accessed with:
Index: guile/guile-core/doc/scheme-modules.texi
diff -u guile/guile-core/doc/scheme-modules.texi:1.5
guile/guile-core/doc/scheme-modules.texi:1.6
--- guile/guile-core/doc/scheme-modules.texi:1.5 Sun Apr 22 07:56:52 2001
+++ guile/guile-core/doc/scheme-modules.texi Wed May 2 07:44:38 2001
@@ -38,8 +38,7 @@
@menu
* Scheme and modules:: How modules are handled in standard Scheme.
* The Guile module system:: How Guile does it.
-* Dynamic Libraries:: Loading libraries of compiled code at run time.
-* Dynamic Linking from Marius::
+* Dynamic Libraries:: Loading libraries of compiled code at run time.
@end menu
@@ -81,42 +80,190 @@
probably change to something more like the ML module system, so for now
I will simply describe how it works for a couple of simple cases.
-First of all, the Guile module system sets up a hierarchical name space,
-and that name space can be represented like Unix pathnames preceded by a
address@hidden character. The root name space for all Guile-supplied modules
-is called @code{ice-9}.
+So for example, the pipe interprocess communication interface
+(REFFIXME), contained in @file{$srcdir/ice-9/popen.scm}, starts out with
-So for example, the SLIB interface, contained in
address@hidden/ice-9/slib.scm}, starts out with
-
@smalllisp
-(define-module (ice-9 slib))
+(define-module (ice-9 popen))
@end smalllisp
and a user program can use
address@hidden
+(use-modules (ice-9 popen))
address@hidden smalllisp
+
+to have access to all procedures and variables exported from the module.
+
address@hidden
+* General Information about Modules:: Guile module basics.
+* Loading Guile Modules:: How to use existing modules.
+* Creating Guile Modules:: How to package your code into modules.
+* More Module Procedures:: Low--level module code.
+* Included Guile Modules:: Which modules come with Guile?
address@hidden menu
+
address@hidden General Information about Modules
address@hidden General Information about Modules
+
+A Guile module is a collection of procedures, variables and syntactic
+forms (macros), which are either public or private. Public bindings are
+in the so--called @dfn{export list} of a module and can be made visible
+to other modules, which import them. This @dfn{module import} is called
address@hidden of a module, and consists of loading of the module code (if
+it has not already been loaded) and making all exported items of the
+loaded module visible to the importing module (@pxref{Loading Guile
+Modules}).
+
+The other side is called @dfn{defining} a module, and consists of giving
+a name to a module, add procedures and variables to it and declare which
+of the names should be exported when another module uses it
+(@pxref{Creating Guile Modules}).
+
+All Guile modules have unique names, which are lists 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} (REFFIXME). The resulting file name is
+then searched in all directories in the variable @code{%load-path}. For
+example, the @code{(ice-9 popen)} module would result in the filename
address@hidden/popen.scm} and searched in the installation directory of
+Guile and in all other directories in the load path.
+
address@hidden 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
address@hidden syntactic form or the @code{#:use-syntax} module
+definition option (@pxref{Creating Guile Modules}).
+
+Please note that there are some problems with the current module system
+you should keep in mind. When importing a module which exports a macro
+definition, the other module must export all bindings the macro
+expansion uses, too, because the expanded code would otherwise not be
+able to see these definitions and issue a ``variable unbound'' error, or
+worse, would use another binding which might be present in the scope of
+the expansion.
+
+When two or more modules are imported, and they export bindings with the
+same names, the last imported module wins, and the exported binding of
+that last module will silently be used. This might lead to
+hard--to--find errors because wrong procedures or variables are used.
+
+
address@hidden Loading Guile Modules
address@hidden Loading Guile Modules
+
address@hidden FIXME::martin: Review me!
+
+There are several modules included in the Guile distribution, and not
+all of the procedures available for Guile are immedietely available when
+you start up the interpreter. Some of the procedures are packaged in
+modules, so that they are only accessible after the user has explicitly
+said that she wants to use them. In Guile, the syntactic form
address@hidden is used for telling the interpreter that he should
+locate the code for a given module, load it and make the exported
+bindings of the module visible to the caller.
+
address@hidden begin (scm-doc-string "boot-9.scm" "use-modules")
address@hidden syntax use-modules module-specification @dots{}
+All @var{module-specification}s are of the form @code{(hierarchy file)}.
+One example of this is
+
@smalllisp
-(use-modules (ice-9 slib))
+(use-modules (ice-9 popen))
@end smalllisp
+
address@hidden allows the current Guile program to use all publicly
+defined procedures and variables in the modules denoted by the
address@hidden
address@hidden deffn
address@hidden end
+
address@hidden FIXME::martin: Is this correct, and is there more to say?
address@hidden FIXME::martin: Define term and concept `system transformer'
somewhere.
+
address@hidden syntax use-syntax module-specification
+Load the module @code{module-specification} and use its system
+transformer as the system transformer for the currently defined module,
+as well as installing it as the current system transformer.
address@hidden deffn
+
-to have access to all procedures and variables defined within the slib
-module with @code{(define-public ...)}.
address@hidden Creating Guile Modules
address@hidden Creating Guile Modules
-So here are the functions involved:
address@hidden FIXME::martin: Review me!
+
+When you want to create your own modules, you have to take the following
+steps:
+
address@hidden @bullet
address@hidden
+Create a Scheme source file and add all variables and procedures you wish
+to export, or which are required by the exported procedures.
+
address@hidden
+Add a @code{define-module} form at the beginning.
+
address@hidden
+Export all bindings which should be visible to importing modules, either
+by using @code{define-public} or @code{export} (both documented below).
address@hidden itemize
+
@c begin (scm-doc-string "boot-9.scm" "define-module")
address@hidden syntax define-module module-specification
address@hidden syntax define-module module-specification [options @dots{}]
@var{module-specification} is of the form @code{(hierarchy file)}. One
example of this is
@smalllisp
-(define-module (ice-9 slib))
+(define-module (ice-9 popen))
@end smalllisp
@code{define-module} makes this module available to Guile programs under
the given @var{module-specification}.
+
+The @var{options} are keyword/value--pairs which specify more about the
+defined module. The recognized options and their meaning is shown in
+the following table.
+
address@hidden @code
address@hidden #:use-module @var{module}
+Equivalent to a @code{(use-modules @var{module})}. Use the specified
address@hidden when loading this module.
+
address@hidden #:use-syntax @var{module}
+Use @var{module} when loading the currently defined module, and install
+it as the syntax transformer.
+
address@hidden #:autoload @var{module} @var{symbol}
+Load @var{module} whenever @var{symbol} is accessed.
+
address@hidden #:export @var{list}
+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.
+
address@hidden #:no-backtrace
+Tell Guile not to record information for procedure backtraces when
+executing the procedures in this module.
+
address@hidden #:pure
+Create a @dfn{pure} module, that is a module which does not contain any
+of the standard procedure bindings except for the syntax forms. This is
+useful if you want to create @dfn{safe} modules, that is modules which
+do not know anything about dangerous procedures.
address@hidden table
+
@end deffn
@c end
address@hidden syntax export variable @dots{}
+Add all @var{variable}s (which must be symbols) to the list of exported
+bindings of the current module.
address@hidden deffn
+
@c begin (scm-doc-string "boot-9.scm" "define-public")
@deffn syntax define-public @dots{}
Makes a procedure or variable available to programs that use the current
@@ -124,165 +271,97 @@
@end deffn
@c end
address@hidden begin (scm-doc-string "boot-9.scm" "use-modules")
address@hidden syntax use-modules module-specification
address@hidden is of the form @code{(hierarchy file)}. One
-example of this is
-
address@hidden
-(use-modules (ice-9 slib))
address@hidden smalllisp
-
address@hidden allows the current Guile program to use all publicly
-defined procedures and variables in the module denoted by
address@hidden
address@hidden deffn
address@hidden end
[FIXME: must say more, and explain, and also demonstrate a private name
space use, and demonstrate how one would do Python's "from Tkinter
import *" versus "import Tkinter". Must also add something about paths
and standards for contributed modules.]
address@hidden More Module Procedures
address@hidden More Module Procedures
+
address@hidden FIXME::martin: Review me!
+
address@hidden FIXME::martin: Should this procedure be documented and supported
address@hidden at all?
+
+The procedures in this section are useful if you want to dig into the
+innards of Guile's module system. If you don't know precisely what you
+do, you should probably avoid using any of them.
+
@deffn primitive standard-eval-closure module
Return an eval closure for the module @var{module}.
@end deffn
+
address@hidden Included Guile Modules
address@hidden Included Guile Modules
+
address@hidden 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 debug)
Mikael Djurfeldt's source-level debugging support for Guile
(@pxref{Debugger User Interface}).
+
@item (ice-9 threads)
Guile's support for multi threaded execution (@pxref{Scheduling}).
address@hidden (ice-9 slib)
-This module contains hooks for using Aubrey Jaffer's portable Scheme
-library SLIB from Guile (@pxref{SLIB}).
address@hidden FIXME::martin: This module is not in the distribution. Remove it
address@hidden from here?
address@hidden (ice-9 jacal)
-This module contains hooks for using Aubrey Jaffer's symbolic math
-packge Jacal from Guile (@pxref{JACAL}).
address@hidden table
address@hidden (ice-9 rdelim)
+Line-- and character--delimited input (REFFIXME).
address@hidden Dynamic Libraries
address@hidden Dynamic Libraries
address@hidden (ice-9 documentation)
+Online documentation (REFFIXME).
-Often you will want to extend Guile by linking it with some existing
-system library. For example, linking Guile with a @code{curses} or
address@hidden library would be useful if you want to implement a
-full-screen user interface for a Guile application. However, if you
-were to link Guile with these libraries at compile time, it would bloat
-the interpreter considerably, affecting everyone on the system even if
-the new libraries are useful only to you. Also, every time a new
-library is installed, you would have to reconfigure, recompile and
-relink Guile merely in order to provide a new interface.
-
-Many Unix systems permit you to get around this problem by using
address@hidden loading}. When a new library is linked, it can be made a
address@hidden library} by passing certain switches to the linker. A
-dynamic library does not need to be linked with an executable image at
-link time; instead, the executable may choose to load it dynamically at
-run time. This is a powerful concept that permits an executable to link
-itself with almost any library without reconfiguration, if it has been
-written properly.
-
-Guile's dynamic linking functions make it relatively easy to write a
-module that incorporates code from third-party object code libraries.
-
address@hidden primitive dynamic-link filename
-Open the dynamic library called @var{filename}. A library
-handle representing the opened library is returned; this handle
-should be used as the @var{dobj} argument to the following
-functions.
address@hidden deffn
address@hidden (srfi srfi-2)
+Support for @code{and-let*} (REFFIXME).
address@hidden primitive dynamic-object? obj
-Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
-otherwise.
address@hidden deffn
address@hidden (srfi srfi-6)
+Support for some additional string port procedures (REFFIXME).
address@hidden primitive dynamic-unlink dobj
-Unlink the indicated object file from the application. The
-argument @var{dobj} must have been obtained by a call to
address@hidden After @code{dynamic-unlink} has been
-called on @var{dobj}, its content is no longer accessible.
address@hidden deffn
address@hidden (srfi srfi-8)
+Multiple--value handling with @code{receive} (REFFIXME).
address@hidden primitive dynamic-func name dobj
-Search the dynamic object @var{dobj} for the C function
-indicated by the string @var{name} and return some Scheme
-handle that can later be used with @code{dynamic-call} to
-actually call the function.
-
-Regardless whether your C compiler prepends an underscore @samp{_} to
-the global names in a program, you should @strong{not} include this
-underscore in @var{function}. Guile knows whether the underscore is
-needed or not and will add it when necessary.
address@hidden deffn
address@hidden (srfi srfi-9)
+Record definition with @code{define-record-type} (REFFIXME).
address@hidden primitive dynamic-call func dobj
-Call the C function indicated by @var{func} and @var{dobj}.
-The function is passed no arguments and its return value is
-ignored. When @var{function} is something returned by
address@hidden, call that function and ignore @var{dobj}.
-When @var{func} is a string , look it up in @var{dynobj}; this
-is equivalent to
address@hidden
-(dynamic-call (dynamic-func @var{func} @var{dobj} #f))
address@hidden smallexample
address@hidden (srfi srfi-10)
+Read--hash extension @code{#,()} (REFFIXME).
-Interrupts are deferred while the C function is executing (with
address@hidden/@code{SCM_ALLOW_INTS}).
address@hidden deffn
address@hidden (srfi srfi-11)
+Multiple--value handling with @code{let-values} and @code{let-values*}
+(REFFIXME).
address@hidden primitive dynamic-args-call func dobj args
-Call the C function indicated by @var{func} and @var{dobj},
-just like @code{dynamic-call}, but pass it some arguments and
-return its return value. The C function is expected to take
-two arguments and return an @code{int}, just like @code{main}:
address@hidden
-int c_func (int argc, char **argv);
address@hidden smallexample
-
-The parameter @var{args} must be a list of strings and is
-converted into an array of @code{char *}. The array is passed
-in @var{argv} and its size in @var{argc}. The return value is
-converted to a Scheme number and returned from the call to
address@hidden
address@hidden deffn
address@hidden (srfi srfi-13)
+String library (REFFIXME).
address@hidden primitive c-registered-modules
-Return a list of the object code modules that have been imported into
-the current Guile process. Each element of the list is a pair whose
-car is the name of the module, and whose cdr is the function handle
-for that module's initializer function. The name is the string that
-has been passed to scm_register_module_xxx.
address@hidden deffn
address@hidden (srfi srfi-14)
+Character--set library (REFFIXME).
address@hidden primitive c-clear-registered-modules
-Destroy the list of modules registered with the current Guile process.
-The return value is unspecified. @strong{Warning:} this function does
-not actually unlink or deallocate these modules, but only destroys the
-records of which modules have been loaded. It should therefore be used
-only by module bookkeeping operations.
address@hidden deffn
address@hidden (srfi srfi-17)
+Getter--with--setter support (REFFIXME).
-[FIXME: provide a brief example here of writing the C hooks for an
-object code module, and using dynamic-link and dynamic-call to load the
-module.]
address@hidden (ice-9 slib)
+This module contains hooks for using Aubrey Jaffer's portable Scheme
+library SLIB from Guile (@pxref{SLIB}).
address@hidden FIXME::martin: This module is not in the distribution. Remove it
address@hidden from here?
address@hidden (ice-9 jacal)
+This module contains hooks for using Aubrey Jaffer's symbolic math
+packge Jacal from Guile (@pxref{JACAL}).
address@hidden table
address@hidden Dynamic Linking from Marius
address@hidden Dynamic Linking from Marius
address@hidden NJFIXME primitive documentation here duplicates (and is generally
address@hidden better than) documentation for the same primitives earlier on.
address@hidden Dynamic Libraries
address@hidden Dynamic Libraries
Most modern Unices have something called @dfn{shared libraries}. This
ordinarily means that they have the capability to share the executable
@@ -319,9 +398,9 @@
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::
@end menu
@node Low level dynamic linking
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- guile/guile-core/doc ChangeLog scheme-io.texi s...,
Martin Grabmueller <=