[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Module introspection API doc
From: |
Ludovic Courtès |
Subject: |
Module introspection API doc |
Date: |
Fri, 14 Dec 2007 18:49:00 +0100 |
User-agent: |
Gnus/5.11 (Gnus v5.11) Emacs/22.1 (gnu/linux) |
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.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Module introspection API doc,
Ludovic Courtès <=