summaryrefslogtreecommitdiff
path: root/doc/ref/api-modules.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2010-07-17 13:30:50 +0200
committerAndy Wingo <wingo@pobox.com>2010-07-17 13:31:06 +0200
commitd68a81e038597ba3d47f39b4cd8a5864953dc1d5 (patch)
treecfc2a94020d063deeb889e4d7ba4718b41e0d12f /doc/ref/api-modules.texi
parent1c05a2a16d845a261bcb0804e7162f31533d674f (diff)
downloadguile-d68a81e038597ba3d47f39b4cd8a5864953dc1d5.tar.gz
recommend #:replace
* doc/ref/api-modules.texi (Creating Guile Modules): Update text to recommend #:replace. * module/srfi/srfi-19.scm (current-time): #:replace.
Diffstat (limited to 'doc/ref/api-modules.texi')
-rw-r--r--doc/ref/api-modules.texi39
1 files changed, 16 insertions, 23 deletions
diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi
index a1aff347e..b412dbe24 100644
--- a/doc/ref/api-modules.texi
+++ b/doc/ref/api-modules.texi
@@ -383,29 +383,22 @@ with the same name that is not also ``replacing''. Normally a
replacement results in an ``override'' warning message,
@code{#:replace} avoids that.
-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 a binding named
-@code{current-input-port} (@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
-@code{#:replace}.
-
-SRFI-19, on the other hand, exports its own version of
-@code{current-time} (@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.
+In general, a module that exports a binding for which the @code{(guile)}
+module already has a definition should use @code{#:replace} instead of
+@code{#:export}. @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.
+
+Note that although it is often a good idea for the replaced binding to
+remain compatible with a binding in @code{(guile)}, to avoid surprising
+the user, sometimes the bindings will be incompatible. For example,
+SRFI-19 exports its own version of @code{current-time} (@pxref{SRFI-19
+Time}) which is not compatible with the core @code{current-time}
+function (@pxref{Time}). Guile assumes that a user importing a module
+knows what she is doing, and uses @code{#:replace} for this binding
+rather than @code{#:export}.
The @code{#:duplicates} (see below) provides fine-grain control about
duplicate binding handling on the module-user side.