Re: Module introspection API doc

Re: Module introspection API doc

[Gregory Marton]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 3659 bytes --]

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 `@pxref' in this context (see the Texinfo manual).  There are
> other incorrect uses of `@pxref'.

Ah, I see, you want me to use @xref because "The parenthetical reference 
command, `@pxref', is nearly the same as `@xref', 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:
> 
>> +@smalllisp
>> +(module-replace! (resolve-module '(srfi srfi-19)) '(current-time))
>> +(use-modules ((srfi srfi-19)))
>> +@end 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}.
>> +@end deffn
> 
> The description is correct.  Use `@code' when referring to functions,
> and no `@pxref' here.

I don't understand.  I'm referring to a variable and a module, no functions -- 
where should I use @code?
For "no `@pxref' 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~~~~^^^^~~~~~--~~~~~~~~~~~~~~~++~~~~~~~

[-- Attachment #2: Type: TEXT/PLAIN, Size: 5763 bytes --]

--- 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:
+@smalllisp
+(module-replace! (resolve-module '(srfi srfi-19)) '(current-time))
+(use-modules ((srfi srfi-19)))
+@end smalllisp
+but you may be better off rewriting your code using a special prefix:
+@smalllisp
+(use-modules ((srfi srfi-19) #:renamer (symbol-prefix-proc 'srfi-19:)))
+@end 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
 
+@deffn {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.
+@end deffn
+
+@deffn {Scheme Procedure} module-name module
+Return the name of the module object @var{module} as a list of symbols.
+@end deffn
+
+@deffn {Scheme Procedure} module-defined? module name
+Return #t iff @var{name} is defined in @var{module} (or in a module
+that @var{module} uses).
+@end deffn
+
+@deffn {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 
+@xref{Variables}.
+@end deffn
+
+@c FIXME: Ludovic, please review carefully?
+@deffn {Scheme Procedure} module-variable module variable
+@deffnx {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}.
+@end deffn
+
+@deffn {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}
+@end deffn
+
+@deffn {Scheme Procedure} module-map proc module
+Call @var{proc} on each symbol in @var{module} with arguments of
+@code{(symbol variable)}, returning a list of the results.
+@end deffn
+
+@deffn {Scheme Procedure} module-for-each proc module
+Call @var{proc} on each symbol in @var{module} with arguments of
+@code{(symbol variable)} for side effects, with an unspecified return
+value.
+@end deffn
+
+@deffn {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
+@dots{}) to have any effect.  The return value is unspecified.
+@end deffn
+
+@deffn {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}).
+@end deffn
+
+@deffn {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
+@dots{}) to have any effect.  The return value is unspecified.
+@end deffn
+
+@deffn {Scheme Procedure} module-remove! module symbol
+Make sure that @var{symbol} is undefined in the local namespace of @var{module}
+@end deffn
+
+@deffn {Scheme Procedure} module-public-interface module
+Return the module object which is the public interface for
+@var{module}.  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}.
+@end deffn
+
+@deffn {Scheme Procedure} module-duplicates-handlers module
+The declared sequence of duplicate-binding-handlers used for this
+module.  The default is given by
+@code{(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.
+@end deffn
+
+
 @node Module System Quirks
 @subsubsection Module System Quirks
 

Re: Module introspection API doc

[Ludovic Courtès]

Hi Gregory,

Gregory Marton <gremio@csail.mit.edu> writes:

> I'm in the process of getting signed and sending in the copyright
> agreement. Thanks for your patience on this doc.

Great!  I'll get back to this once the FSF has received/signed your
form.

Thanks,
Ludovic.