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

[Ludovic Courtès]

Hi,

It occurred to me that `define-module' is only partially documented, in
particular, `#:re-export', `#:replace' and `#:duplicates' are not
documented at all.

I tried to do my best to document them accurately but note that (i) I'm
not a native English speaker and (ii) from the discussion we've had with
Kevin, it seems that we disagree on the use of `#:replace'.  In
particular, I used `(srfi srfi-19)' as an example of when to use
`#:replace' and Kevin may disagree with that.  But, well, let's debate
this question.  ;-)

Thanks,
Ludovic.


2005-10-21  Ludovic Courtès  <address@hidden>

        * doc/ref/api-modules.texi (Creating Guile Modules): Documented
          `#:re-export', `#:export-syntax', `#:re-export-syntax',
          `#:replace' and `#:duplicates'.


--- orig/doc/ref/api-modules.texi
+++ mod/doc/ref/api-modules.texi
@@ -240,6 +240,7 @@
 module to be accessed, but also selects bindings from it and renames
 them to suit the current module's needs.  For example:
 
address@hidden binding renamer
 @smalllisp
 (use-modules ((ice-9 popen)
               :select ((open-pipe . pipe-open) close-pipe)
@@ -305,6 +306,7 @@
 
 @var{spec} can also be of the form:
 
address@hidden binding renamer
 @smalllisp
  (MODULE-NAME [:select SELECTION] [:renamer RENAMER])
 @end smalllisp
@@ -419,9 +421,152 @@
 
 @item #:export @var{list}
 @cindex export
-Export all identifiers in @var{list}, which must be a list of symbols.
+Export all identifiers in @var{list} which must be a list of symbols.
 This is equivalent to @code{(export @var{list})} in the module body.
 
address@hidden #:re-export @var{list}
address@hidden re-export
+Re-export all identifiers in @var{list} which must be a list of
+symbols.  The symbols in @var{list} must be imported by the current
+module from other modules.  This is equivalent to @code{(re-export
address@hidden)} in the module body.
+
address@hidden #:export-syntax @var{list}
address@hidden export-syntax
+Export all identifiers in @var{list} which must be a list of symbols.
+The identifiers in @var{list} must refer to macros (@pxref{Macros})
+defined in the current module.  This is equivalent to
address@hidden(export-syntax @var{list})} in the module body.
+
address@hidden #:re-export-syntax @var{list}
address@hidden re-export-syntax
+Re-export all identifiers in @var{list} which must be a list of
+symbols.  The symbols in @var{list} must refer to macros imported by
+the current module from other modules.  This is equivalent to
address@hidden(re-export-syntax @var{list})} in the module body. 
+
address@hidden #:replace @var{list}
address@hidden replace
address@hidden replacing binding
address@hidden overriding binding
address@hidden duplicate binding
+Export all identifiers in @var{list} (a list of symbols) and mark them
+as @dfn{replacing bindings}.  In the module user's name space, this
+will have the effect of replacing any binding with the same name that
+is not ``replacing'' itself.
+
+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.
+
address@hidden core binding
address@hidden current-time
+One example of this is @code{(srfi srfi-19)} which exports
address@hidden (@pxref{SRFI-19 Time}), thus overriding the core
+binding with the same name (@pxref{Time}).  If @code{(srfi srfi-19)}
+was defined as follows:
+
address@hidden
+(define-module (srfi srfi-19)
+  #:export (current-time ...))
address@hidden smalllisp
+
+Then, by default, the user module that performs @code{(use-modules
+(srfi srfi-19))} will get SRFI-19's version of @code{current-time}.
+However, Guile will also issue a warning about the core binding being
+replaced potentially unwillingly:
+
address@hidden
+guile> (use-modules (srfi srfi-19))
+WARNING: (guile-user): imported module (srfi srfi-19) overrides core binding 
`current-time'
address@hidden smallexample
+
address@hidden:replace} is a way to fix this issue by making it explicit that
+the binding-providing module does want to override a core binding:
+
address@hidden
+(define-module (srfi srfi-19)
+  #:export (...)
+  #:replace (current-time))
address@hidden smalllisp
+
address@hidden binding renamer
+In this case, this can be considered harmless since the user of this
+module expects @code{current-time} to refer to SRFI-19's
+implementation, and not to the Guile built-in version.  However, note
+that this does not preclude the use of both versions of the binding
+within a given module: this can be done using the @code{#:renamer}
+option of @code{use-modules} (@pxref{Using Guile Modules}).
+
+The @code{#:duplicates} option (below) provides fine-grain control
+about duplicate binding handling on the module-user side.
+
address@hidden #:duplicates @var{list}
address@hidden duplicate binding handlers
address@hidden duplicate binding
address@hidden overriding binding
+Tell Guile to handle duplicate bindings for the bindings imported by
+the current module according to the policy defined by @var{list}, a
+list of symbols.  @var{list} must contain symbols representing a
+duplicate binding handling policy chosen among the following:
+
address@hidden @code
address@hidden check
+Raises an error when a binding is imported from more than one place.
address@hidden warn
+Issue a warning when a binding is imported from more than one place
+and leave the responsibility of actually handling the duplication to
+the next duplicate binding handler.
address@hidden replace
+When a new binding is imported that has the same name as a previously
+imported binding, then do the following:
+
address@hidden
address@hidden
address@hidden replacing binding
+If the old binding was said to be @dfn{replacing} (via the
address@hidden:replace} option) and the new binding is not replacing, the
+keep the old binding.
address@hidden
+If the old binding was not said to be replacing and the new binding is
+replacing, then replace the old binding with the new one.
address@hidden
+If neither the old nor the new binding is replacing, then keep the old
+one.
address@hidden enumerate
+
address@hidden warn-override-core
+Issue a warning when a core binding is being overwritten and actually
+override the core binding with the new one.
address@hidden first
+In case of duplicate bindings, the firstly imported binding is always
+the one which is kept.
address@hidden last
+In case of duplicate bindings, the lastly imported binding is always
+the one which is kept.
address@hidden noop
+In case of duplicate bindings, leave the responsibility to the next
+duplicate handler.
address@hidden table
+
+If @var{list} contains more than one symbol, then the duplicate
+binding handlers which appear first will be used first when resolving
+a duplicate binding situation.  As mentioned above, some resolution
+policies may explicitly leave the responsibility of handling the
+duplication to the next handler in @var{list}.
+
address@hidden default-duplicate-binding-handler
+The default duplicate binding resolution policy is given by the
address@hidden procedure and is currently
+equal to:
+
address@hidden
+(replace warn-override-core warn last)
address@hidden smalllisp
+
 @item #:no-backtrace
 @cindex no backtrace
 Tell Guile not to record information for procedure backtraces when
@@ -449,6 +594,12 @@
 @end deffn
 @c end
 
address@hidden syntax re-export variable @dots{}
+Add all @var{variable}s (which must be symbols) to the lits of
+re-exported bindings of the current module.  Re-exported bindings must
+be imported by the current module from some other(s) module(s).
address@hidden deffn
+
 @node Module System Reflection
 @subsubsection Module System Reflection