Module introspection API doc

[Ludovic Courtès]

Hi,

Gregory Marton <address@hidden> once sent me a patch documenting
parts of the introspection API (thank you!).  For the record, I'm
commenting it here.

Gregory: could you post an updated patch based on the comments below
(make sure to send it to the list)?  I'll send you off-line the required
paperwork for copyright assignment to the FSF.

>  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.  :-)

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

> +System Reflection} to tell it to use @code{#:replace} anyway:

> address@hidden
> +(module-replace! (resolve-module '(srfi srfi-19)) '(current-time))
> +(use-modules ((srfi srfi-19)))
> address@hidden smalllisp

This one is actually a hack, and we probably don't want to recommend it.

> +The declared set of duplicate binding handlers for a given module can
> +be found with using @pxref{Module Reflection}

Again address@hidden' is inappropriate, and there should be a period.

> address@hidden {Scheme Procedure} module-ref module symbol . default

I'd write "[default]" instead since it's an optional argument.

> address@hidden FIXME: Ludovic, please review carefully?
> address@hidden {Scheme Procedure} module-variable module variable
> address@hidden {C Function} module-reverse-lookup module variable

C function names are unlikely to contains hyphens.  ;-)
It should be "scm_variable", `module-reverse-lookup' is another thing.

> +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}.
> address@hidden deffn

The description is correct.  Use address@hidden' when referring to functions,
and no address@hidden' here.

> address@hidden {Scheme Procedure} module-map proc module
> +Call @var{proc} on each symbol in @var{module} with arguments of
> address@hidden(symbol variable)}, returning a list of the results.
> address@hidden(module-for-each proc module)} is similar, but the return value
> +is unspecified.

Add a different entry for `module-for-each'.

> address@hidden {Scheme Procedure} module-export! module exports-list
> +Add the module-defined symbols in @var{exports-list} to the public
> +interface for @var{module}.  This should be done before (use-modules
> address@hidden) to have any effect.  The return value is unspecified.

I don't get the "should be done before ...", what did you mean?

> address@hidden {Scheme Procedure} module-replace! module replacements)

Trailing bracket.

> +Add the the module-defined symbols in @var{replacements} to the public
> +interface for @var{module} and set their 'replace property, so that

I'd remove "and set their 'replace property" since that's an
implementation detail.

> +they will silently override any pre-existing conflicting symbols in
> +the importing environment.

I'd add "provided users of @var{module} use the @code{replace} duplicate
binding handler (@pxref{Creating Guile Modules, the @code{#:replace}
option})."

> address@hidden {Scheme Procedure} module-re-export! module re-exports-list
> +Add the module-imported symbols in @var{exports-list} to the public

Should be "@var{re-exports-list}".

> +interface for @var{module}.  This should be done before (use-modules

Same question about "should be done before".

> address@hidden {Scheme Procedure} module-duplicates-handlers module
> +The declared sequence of duplicate-binding-handlers used for this
> +module.  The default is given by
> address@hidden(default-duplicate-binding-handler)} and the declared list can
> +be modified using @code{(set-module-duplicates-handlers! module
> +list)}.  For detailed information on how to write your own duplicate
> +handler, see the documentation inside boot-9.scm.

We can't ask people to look into `boot-9.scm' (well, we sometimes do but
let's try to avoid it ;-)).  For now, we'll assume that the existing set
of handlers is "enough for everyone".

Thanks,
Ludovic.