From: ludovic.courtes@laas.fr (Ludovic Courtès)
Subject: Re: [PATCH] Augmenting the doc of `define-module'
Date: Mon, 07 Nov 2005 11:18:12 +0100 [thread overview]
Message-ID: <87u0eosqvv.fsf@laas.fr> (raw)
In-Reply-To: <87hdaqvkkm.fsf@zip.com.au> (Kevin Ryde's message of "Sun, 06 Nov 2005 08:41:45 +1100")
Hi Kevin,
Kevin Ryde <user42@zip.com.au> writes:
> ludovic.courtes@laas.fr (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 <ludovic.courtes@laas.fr>
* api-modules.texi (Using Guile Modules): Document SRFI-19 as an
example usage of `#:replace'.
srfi/ChangeLog
2005-11-07 Ludovic Courtès <ludovic.courtes@laas.fr>
* srfi-19.scm (current-time): Replace it instead of exporting
it.
* srfi-34.scm (raise): Likewise.
* srfi-60.scm (bit-count): Likewise.
\f
--- 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
+@code{current-time} (@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.
-@code{#: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
-@code{default-duplicate-binding-handler} procedure, and is
+@code{default-duplicate-binding-handler} 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")
_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel
next prev parent reply other threads:[~2005-11-07 10:18 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2005-10-21 12:59 [PATCH] Augmenting the doc of `define-module' Ludovic Courtès
2005-10-23 21:15 ` Kevin Ryde
2005-10-24 8:21 ` Ludovic Courtès
2005-10-24 21:29 ` Kevin Ryde
2005-10-25 7:34 ` Ludovic Courtès
2005-11-05 21:41 ` Kevin Ryde
2005-11-07 10:18 ` Ludovic Courtès [this message]
2005-11-17 17:17 ` Ludovic Courtès
2005-12-05 12:07 ` Ludovic Courtès
2005-12-07 0:31 ` Marius Vollmer
2005-12-07 8:12 ` Ludovic Courtès
2006-02-21 8:42 ` Use of `:replace' in some SRFI modules Ludovic Courtès
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87u0eosqvv.fsf@laas.fr \
--to=ludovic.courtes@laas.fr \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).