[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] Augmenting the doc of `define-module'
From: |
Ludovic Courtès |
Subject: |
Re: [PATCH] Augmenting the doc of `define-module' |
Date: |
Mon, 07 Nov 2005 11:18:12 +0100 |
User-agent: |
Gnus/5.110004 (No Gnus v0.4) Emacs/21.4 (gnu/linux) |
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")