Re: [PATCH] Augmenting the doc of `define-module'

[Ludovic Courtès]

Hi Kevin,

Kevin Ryde <address@hidden> writes:

> address@hidden (Ludovic Courtès) writes:
>>
>> "replaces" `current-time' instead of exporting it.  Once this is
>> done,
>
> Well, certainly not until then.  I removed this bit I didn't like and
> checked-in the rest.  Thanks.

Thanks for checking in the rest.  The patch below atomically updates
both SRFI-19 and the manual so that it mentions it as an example.  I
notice that you have a tendency to be extremely concise, even when
writing documentation, which I seem to be lacking.  ;-)

Thanks,
Ludovic.


doc/ref/ChangeLog

2005-11-07  Ludovic Courtès  <address@hidden>

        * api-modules.texi (Using Guile Modules): Document SRFI-19 as an
        example usage of `#:replace'.


srfi/ChangeLog

2005-11-07  Ludovic Courtès  <address@hidden>

        * srfi-19.scm (current-time): Replace it instead of exporting
        it.

        * srfi-34.scm (raise): Likewise.

        * srfi-60.scm (bit-count): Likewise.



--- orig/doc/ref/api-modules.texi
+++ mod/doc/ref/api-modules.texi
@@ -456,17 +456,27 @@
 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.
+
+
+For instance, SRFI-39 exports @code{current-input-port}
+(@pxref{SRFI-39}) in an upwardly compatible way.  SRFI-19, on the
+other hand, exports its own, incompatible version of
address@hidden (@pxref{SRFI-19 Time}), purposefully overriding
+the core binding with the same name (@pxref{Time}).
 
 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.
 
address@hidden:duplicates} below provides fine-grain control about duplicate
-binding handling on the module-user side.
+The @code{#:duplicates} option (below) provides fine-grain control
+about duplicate binding handling on the module-user side.
 
 @item #:duplicates @var{list}
 @cindex duplicate binding handlers
@@ -524,7 +534,7 @@
 
 @findex default-duplicate-binding-handler
 The default duplicate binding resolution policy is given by the
address@hidden procedure, and is
address@hidden procedure, and is equal to:
 
 @smalllisp
 (replace warn-override-core warn last)


--- orig/srfi/srfi-19.scm
+++ mod/srfi/srfi-19.scm
@@ -41,13 +41,19 @@
 (define-module (srfi srfi-19)
   :use-module (srfi srfi-6)
   :use-module (srfi srfi-8)
-  :use-module (srfi srfi-9))
+  :use-module (srfi srfi-9)
 
-(begin-deprecated
- ;; Prevent `export' from re-exporting core bindings.  This behaviour
- ;; of `export' is deprecated and will disappear in one of the next
- ;; releases.
- (define current-time #f))
+  ;; CURRENT-TIME replaces a core binding.  Instead of simply exporting it
+  ;; (which yields an error message by default) or overriding the core
+  ;; binding with `set!' (which would make the original version of
+  ;; CURRENT-TIME unavailable), we mark it as a replacing binding.
+  ;; Consequently, this will silently replace CURRENT-TIME in the module
+  ;; user's namespace.
+  ;;
+  ;; The rationale is that the module user knows about this and can still
+  ;; find means to access the core definition of CURRENT-TIME if need be
+  ;; (e.g. via a renamer).
+  :replace (current-time))
 
 (export ;; Constants
            time-duration
@@ -60,7 +66,6 @@
            current-date
            current-julian-day
            current-modified-julian-day
-           current-time
            time-resolution
            ;; Time object and accessors
            make-time


--- orig/srfi/srfi-34.scm
+++ mod/srfi/srfi-34.scm
@@ -27,8 +27,8 @@
 ;;; Code:
 
 (define-module (srfi srfi-34)
-  #:export (with-exception-handler
-           raise)
+  #:export (with-exception-handler)
+  #:replace (raise)
   #:export-syntax (guard))
 
 (cond-expand-provide (current-module) '(srfi-34))


--- orig/srfi/srfi-60.scm
+++ mod/srfi/srfi-60.scm
@@ -22,7 +22,6 @@
            bitwise-xor
            bitwise-not
            any-bits-set?
-           bit-count
            bitwise-if bitwise-merge
            log2-binary-factors first-set-bit
            bit-set?
@@ -42,7 +41,8 @@
               logtest
               logcount
               logbit?
-              ash))
+              ash)
+  #:replace (bit-count))
 
 (load-extension "libguile-srfi-srfi-60-v-1" "scm_init_srfi_60")