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 <[EMAIL PROTECTED]>
* 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:
[EMAIL PROTECTED] 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:
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] #:re-export @var{list}
[EMAIL PROTECTED] 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
[EMAIL PROTECTED])} in the module body.
+
[EMAIL PROTECTED] #:export-syntax @var{list}
[EMAIL PROTECTED] 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
[EMAIL PROTECTED](export-syntax @var{list})} in the module body.
+
[EMAIL PROTECTED] #:re-export-syntax @var{list}
[EMAIL PROTECTED] 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
[EMAIL PROTECTED](re-export-syntax @var{list})} in the module body.
+
[EMAIL PROTECTED] #:replace @var{list}
[EMAIL PROTECTED] replace
[EMAIL PROTECTED] replacing binding
[EMAIL PROTECTED] overriding binding
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] core binding
[EMAIL PROTECTED] current-time
+One example of this is @code{(srfi srfi-19)} which exports
[EMAIL PROTECTED] (@pxref{SRFI-19 Time}), thus overriding the core
+binding with the same name (@pxref{Time}). If @code{(srfi srfi-19)}
+was defined as follows:
+
[EMAIL PROTECTED]
+(define-module (srfi srfi-19)
+ #:export (current-time ...))
[EMAIL PROTECTED] 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:
+
[EMAIL PROTECTED]
+guile> (use-modules (srfi srfi-19))
+WARNING: (guile-user): imported module (srfi srfi-19) overrides core binding
`current-time'
[EMAIL PROTECTED] smallexample
+
[EMAIL PROTECTED]:replace} is a way to fix this issue by making it explicit that
+the binding-providing module does want to override a core binding:
+
[EMAIL PROTECTED]
+(define-module (srfi srfi-19)
+ #:export (...)
+ #:replace (current-time))
[EMAIL PROTECTED] smalllisp
+
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] #:duplicates @var{list}
[EMAIL PROTECTED] duplicate binding handlers
[EMAIL PROTECTED] duplicate binding
[EMAIL PROTECTED] 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:
+
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] check
+Raises an error when a binding is imported from more than one place.
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] replace
+When a new binding is imported that has the same name as a previously
+imported binding, then do the following:
+
[EMAIL PROTECTED]
[EMAIL PROTECTED]
[EMAIL PROTECTED] replacing binding
+If the old binding was said to be @dfn{replacing} (via the
[EMAIL PROTECTED]:replace} option) and the new binding is not replacing, the
+keep the old binding.
[EMAIL PROTECTED]
+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.
[EMAIL PROTECTED]
+If neither the old nor the new binding is replacing, then keep the old
+one.
[EMAIL PROTECTED] enumerate
+
[EMAIL PROTECTED] warn-override-core
+Issue a warning when a core binding is being overwritten and actually
+override the core binding with the new one.
[EMAIL PROTECTED] first
+In case of duplicate bindings, the firstly imported binding is always
+the one which is kept.
[EMAIL PROTECTED] last
+In case of duplicate bindings, the lastly imported binding is always
+the one which is kept.
[EMAIL PROTECTED] noop
+In case of duplicate bindings, leave the responsibility to the next
+duplicate handler.
[EMAIL PROTECTED] 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}.
+
[EMAIL PROTECTED] default-duplicate-binding-handler
+The default duplicate binding resolution policy is given by the
[EMAIL PROTECTED] procedure and is currently
+equal to:
+
[EMAIL PROTECTED]
+(replace warn-override-core warn last)
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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).
[EMAIL PROTECTED] deffn
+
@node Module System Reflection
@subsubsection Module System Reflection
_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel
