Hi Ludovic,
I'm in the process of getting signed and sending in the copyright agreement.
Thanks for your patience on this doc.
I've replied below only on the places where you suggested a change that I
didn't take verbatim with thanks, or where I wanted to clarify. I truly
appreciate your time in reviewing this documentation.
More advanced module systems have become a common feature in recently
-designed languages: ML, Python, Perl, and Modula 3 all allow the
+designed languages: ML, Python, Perl, Ruby, and Modula 3 all allow the
This is not meant to be an exhaustive list so we can leave it as is, even if
you really like Ruby. :-)
I understood the intent here to list popular languages that the reader may be
familiar with, to give them a foothold for the advanced concepts. Ruby's module
system seems to me to be interestingly different from the others, and more
closely aligned to Scheme's module system than is Perl's for instance. The
list seems to have a gaping hole without it.
While I think the change makes sense on its merits, do you find it so much less
readable with the extra word that you'd quelch a new contributor's fun? :-)
@emph{renaming} of objects from a foreign module, so they will not
clutter the global name space.
@cindex name space - private
@@ -472,7 +472,15 @@
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}.
+SRFI-19 does not use @code{#:replace}. You can use @pxref{Module
Don't use [EMAIL PROTECTED]' in this context (see the Texinfo manual). There
are
other incorrect uses of [EMAIL PROTECTED]'.
Ah, I see, you want me to use @xref because "The parenthetical reference
command, [EMAIL PROTECTED]', is nearly the same as [EMAIL PROTECTED]', but you use it _only_ inside
parentheses". My bad. I think I've search-and-replaced correctly.
+System Reflection} to tell it to use @code{#:replace} anyway:
[EMAIL PROTECTED]
+(module-replace! (resolve-module '(srfi srfi-19)) '(current-time))
+(use-modules ((srfi srfi-19)))
[EMAIL PROTECTED] smalllisp
This one is actually a hack, and we probably don't want to recommend it.
What shall we recommend? This is what was recommended to me, and what folks
using Google will find, and it works well. If it's in the documentation, then
we can later deprecate it, whereas if it's in the wild, people will get
frustrated with the doc, and find it anyway.
I could add a warning, "This is a hack, and is not recommended."?
+Return the local variable associated with the symbol @var{variable} in
+the module @var{module}, or in any of the modules it uses. This
+differs from module-ref in that it returns the variable object itself,
+rather than the value of the variable: See @pxref{Variables}.
[EMAIL PROTECTED] deffn
The description is correct. Use [EMAIL PROTECTED]' when referring to functions,
and no [EMAIL PROTECTED]' here.
I don't understand. I'm referring to a variable and a module, no functions --
where should I use @code?
For "no [EMAIL PROTECTED]' here", do you mean there shouldn't be an @xref
either?
I didn't change anything here yet.
Thank you for the many changes which are reflected in the attached diff without
response comment.
Best wishes,
Grem
--
------ __@ Gregory A. Marton http://csail.mit.edu/~gremio/
--- _`\<,_ .
-- (*)/ (*) Smoking cures ham.
~~~~~~~~~~~~~~~~-~~~~~~~~_~~~_~~~~~v~~~~^^^^~~~~~--~~~~~~~~~~~~~~~++~~~~~~~
--- doc/ref/api-modules.texi.1.8.3 2007-07-10 18:27:30.000000000 -0400
+++ doc/ref/api-modules.texi 2008-01-25 20:48:50.000000000 -0500
@@ -33,7 +33,7 @@
another module with different names.
More advanced module systems have become a common feature in recently
-designed languages: ML, Python, Perl, and Modula 3 all allow the
+designed languages: ML, Python, Perl, Ruby, and Modula 3 all allow the
@emph{renaming} of objects from a foreign module, so they will not
clutter the global name space.
@cindex name space - private
@@ -472,7 +472,15 @@
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}.
+SRFI-19 does not use @code{#:replace}. You can use @xref{Module System
Reflection} to tell it to use @code{#:replace} anyway:
[EMAIL PROTECTED]
+(module-replace! (resolve-module '(srfi srfi-19)) '(current-time))
+(use-modules ((srfi srfi-19)))
[EMAIL PROTECTED] smalllisp
+but you may be better off rewriting your code using a special prefix:
[EMAIL PROTECTED]
+(use-modules ((srfi srfi-19) #:renamer (symbol-prefix-proc 'srfi-19:)))
[EMAIL PROTECTED] smalllisp
The @code{#:replace} option can also be used by a module which is
intentionally producing a new special kind of environment and should
@@ -545,6 +553,9 @@
(replace warn-override-core warn last)
@end smalllisp
+The declared set of duplicate binding handlers for a given module can
+be found with using @xref{Module Reflection}.
+
@item #:no-backtrace
@cindex no backtrace
Tell Guile not to record information for procedure backtraces when
@@ -632,6 +643,95 @@
likely be a module returned by @code{resolve-interface}.
@end deffn
[EMAIL PROTECTED] {Scheme Procedure} module-define! module name value
+Define the @var{name} in @var{module} to mean @var{value}, adding it
+to the module if necessary. The return value is unspecified.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} module-name module
+Return the name of the module object @var{module} as a list of symbols.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} module-defined? module name
+Return #t iff @var{name} is defined in @var{module} (or in a module
+that @var{module} uses).
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} module-ref module symbol [default]
+Return the value of @var{symbol} in @var{module} or in any of its used
+modules. If there is no such variable, then if @var{default} is
+present, it is returned; otherwise an error is signaled. See also
[EMAIL PROTECTED]
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] FIXME: Ludovic, please review carefully?
[EMAIL PROTECTED] {Scheme Procedure} module-variable module variable
[EMAIL PROTECTED] {C Function} module_reverse_lookup module scm_variable
+Return the local variable associated with the symbol @var{variable} in
+the module @var{module}, or in any of the modules it uses. This
+differs from module-ref in that it returns the variable object itself,
+rather than the value of the variable: See @xref{Variables}.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} module-set! module symbol value
+Set the value of @var{symbol} in @var{module} to @var{value}. If
+there is no such variable, an error is signaled. The return value is
+unspecified. See also @xref{Variables}
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} module-map proc module
+Call @var{proc} on each symbol in @var{module} with arguments of
[EMAIL PROTECTED](symbol variable)}, returning a list of the results.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} module-for-each proc module
+Call @var{proc} on each symbol in @var{module} with arguments of
[EMAIL PROTECTED](symbol variable)} for side effects, with an unspecified return
+value.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} module-export! module exports-list
+Add the module-defined symbols in @var{exports-list} to the public
+interface for @var{module}. This must be called before (use-modules
[EMAIL PROTECTED]) to have any effect. The return value is unspecified.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} module-replace! module replacements
+Add the the module-defined symbols in @var{replacements} to the public
+interface for @var{module}, so that they will silently override any
+pre-existing conflicting symbols in the importing environment,
+provided users of @var{module} use the @code{replace} duplicate
+binding handler (@pxref{Creating Guile Modules, the @code{#:replace}
+option}).
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} module-re-export! module re-exports-list
+Add the module-imported symbols in @var{re-exports-list} to the public
+interface for @var{module}. This must be called before (use-modules
[EMAIL PROTECTED]) to have any effect. The return value is unspecified.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} module-remove! module symbol
+Make sure that @var{symbol} is undefined in the local namespace of @var{module}
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} module-public-interface module
+Return the module object which is the public interface for
[EMAIL PROTECTED] For more about the relationships between the public
+interface for a module and its custom interfaces created on the fly,
+see @xref{General Information about Modules}.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Scheme Procedure} module-duplicates-handlers module
+The declared sequence of duplicate-binding-handlers used for this
+module. The default is given by
[EMAIL PROTECTED](default-duplicate-binding-handler)} and the declared list can
+be modified using @code{(set-module-duplicates-handlers! module
+list)}. Detailed information on how to write your own duplicate
+handler is available in maintainer comments.
[EMAIL PROTECTED] deffn
+
+
@node Module System Quirks
@subsubsection Module System Quirks
