[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] Augmenting the doc of `define-module'
From: |
Marius Vollmer |
Subject: |
Re: [PATCH] Augmenting the doc of `define-module' |
Date: |
Wed, 07 Dec 2005 02:31:06 +0200 |
User-agent: |
Gnus/5.11 (Gnus v5.11) Emacs/22.0.50 (gnu/linux) |
address@hidden (Ludovic Courtès) writes:
> Any news regarding this patch?
I made the following changes. OK?
Index: api-modules.texi
===================================================================
RCS file: /cvsroot/guile/guile/guile-core/doc/ref/api-modules.texi,v
retrieving revision 1.11
diff -u -r1.11 api-modules.texi
--- api-modules.texi 5 Nov 2005 21:38:49 -0000 1.11
+++ api-modules.texi 7 Dec 2005 00:28:42 -0000
@@ -456,17 +456,32 @@
is not also ``replacing''. Normally a replacement results in an
``override'' warning message, @code{#:replace} avoids that.
-This can be used by a module extending a core function in an upwardly
-compatible way, like SRFI-39 @code{current-input-port}
-(@pxref{SRFI-39}).
+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.
-Or it can 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.
+For instance, SRFI-39 exports a binding named
address@hidden (@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
address@hidden:replace}.
address@hidden:duplicates} below provides fine-grain control about duplicate
-binding handling on the module-user side.
+SRFI-19, on the other hand, exports its own version of
address@hidden (@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
--
GPG: D5D4E405 - 2F9B BCCC 8527 692A 04E3 331E FAF8 226A D5D4 E405