Re: What replaces scm_register_module_xxx (Doc update?)

[Dirk Herrmann]

Hi, 

I have some comments and questions regarding the text.

On 12 Aug 2002, Marius Vollmer wrote:

> A Guile module is a data structure with the features described in the
> following sections.  You can work directly with the data structure in
> your programs, but normally you refer to them indirectly via the
> familiar hierachical names like @code{(ice-9 popen)}.

I think it would be helpfull to explain that there is no relationship
between modules named (a b) and (a b c).  People might assume that there
is some subset/superset relationship.  Especially since I remember that
once there was such a concept in guile.

> @deffn Procedure find-module name
> @deffnx Setter (set! (find-module name) module)
> The procedure @code{find-module} returns the module that has most
> recently been registered with the name @var{NAME}.  When no module has
> been registered under @var{NAME}, return @code{#f}.

I'd find it clearer when registering a module would be done using a
function 'register-module' instead of using a setter.  And, the
possibility to register a module implies that people can create modules
dynamically.  But, there are no functions described to create modules
dynamically.

> @c I think the following paragraph is confusing here, especially
> @c given that there are objects called ``envrionments'' in Guile
> @c that are really modules. - mvo

Yes, we should attempt to be cleaner with our names.  Environments should
be used for lexical environments.  I also don't like the name 'variable'
since it rather names a location than a variable.  'Location', on the
other hand, is also not quite accurate, since local variables are also
stored in locations, but for these there are no variables.  At least we
should not use names used in R5RS to name concepts which are not exactly
the same.

> @c An environment is a mapping from identifiers (or symbols) to
> @c locations, i.e., a set of bindings.  There are top-level environments
> @c and lexical environments.  Environment in which a lambda is excuted is
> @c remembered as part of its definition.

What is the relationship between modules and top-level environments then?

> You can only add to the set of bindings of a module, you can not
> remove bindings.  Also, you can only have a single binding for each
> symbol in the set.  As a consequence, once you have added a local or
> imported binding to a module, it can not be changed.  Attempting to
> bind a symbol to the same object that it is already bound to is
> silently ignored.

With respect to modules this means that there is no undelete.  Good.  And,
if this also applies to top-level environments, then memoization of
variable locations can be used.

> These rules ensure that a module can only evolve in a simple manner.
> Once you have looked up a binding in a module, you can be sure that it
> remains valid and that all lookups with the same symbol in a module
> will return the same binding.  When you need to make changes to a
> module that are not allowed by these rules, you must abandon the old
> module and create a new one.  Modules that use the old module in some
> way need to be reconstructed as well, and so on.  See @pref{FIXME} for
> more information about this.

Hmmm.  This needs to be clarified, especially with respect to memoized
code.

> When Guile executes or compiles some code, it does this always in the
> context of a module.  That module is called the @dfn{current module}.
> Set settable procedure @code{current-module} can be used to access the
> current module.  The global identifiers of the executed or compiled
> code are looked up by finding the object that is bound to the
> identifier symbol in the current module.  In certain contexts, the
> object must be a variable so that it can be referenced or set, in
> others, it is also allowed to be a macro transformer which is then used
> to expand the evaluated form.

I think this paragraph is incorrect:  Only when guile executes some
top-level expressions the lookups are done in the current module.  In
other words, while executing a top-level expression, the current-module
corresponds to the top-level environment of that expression.  When a
closure is created, is closes over the current top-level environment.  As
soon as a closure is executed, it is executed in the context of the module
that corresponded to the top-level environment at the creation of the
closure.

> Execution of a @code{define} form can add a new variable binding to
> the current module.  When the symbol in the @code{define} form is
> already bound to a variable, the binding itself is not changed, only
> the value of the variable.  When the symbol is bound but not to a
> variable, an error is signalled.

Maybe some clarification would be helpfull:  There are also internal
defines, which are not meant here.

> To access bindings from another module, the desired bindings are
> simply copied into the accessing module.  There are several ways to
> select which bindings to copy exactly and how to transform the symbols
> on the way.  Ultimately, however, imported bindings are added just
> like local bindings.

That means, modifying a value at the location of a binding will also
modify the value for the source module.

> Note in the previous example that if the current module had already
> defined @code{open-pipe}, adding the binding from @code{(ice-9 popen)}
> would have resulted in an error.  For this reason (and others), there
> is a second variation of interface specification that not only names a
> module to be accessed, but also selects bindings from it and renames
> them to suit the current module's needs.  For example:

Ahh.  Conflicting imports will result in errors.  But:  What happens if an
imported binding is overwritten by 'define' in the current module?
According to R5RS, in such a case 'define' becomes 'set!'.  And this would
influence the source module of the definition.  Hmmm.

> The second variant of @var{spec} is
> 
> @smalllisp
>  (MODULE-NAME [:select SELECTION] [:renamer RENAMER])
> @end smalllisp

Can one use the same module several times, every time specifying some
different SELECTION and RENAMER?  Can the same variable be imported
several times under different names?

Best regards,
Dirk