for review: add nested modules [5/5]

[Peter Schachte]

On Thu, 26 Feb 1998, Fergus Henderson wrote:

> @@ -969,6 +967,7 @@
>  
>  There must only be one predicate with a given name and arity in each module,
>  and only one function with a given name and arity in each module.
> +It is an error to declare the same predicate or function twice.

s/\./ in the same module./

> +Each module must start with a @samp{:- module @var{ModuleName}}
> +declaration, specifying the name of the module. 

I thought you said this isn't the case now.

> +The interface section can contain declarations or definitions of types,

insert `and' or `as well as' here.

> +A @samp{:- implementation.} declaration indicates

s/A /An /

> +The module may optionally end with a @samp{:- end_module @var{ModuleName}}
> +declaration; the name specified in the @samp{end_module} be the

s/be/must be/

Also, you should mention what happens to declarations and definitions
that appear after the end_module directive (outside any module).

> - at c XXX should we mention multipart interfaces and implementations?
> + at c should we mention multipart interfaces and implementations?
>  @c ===> no

I think it's worth mentioning that a module may have multiple
interface and implementation sections.

>  If a module wishes to make use of entities exported by other modules,
>  then it must explicitly import those modules using one or more 
> - at code{import_module} or @code{use_module} declarations.
> + at samp{:- import_module @var{Modules}} or @samp{:- use_module @var{Modules}}
> +declarations.  In both cases, @var{Modules} is a comma-separated list of
> +(fully-qualified) module names.

I don't think you mean fully-qualified.  Will you have to write

	:- import_module :std:list.

to import the list module?

> @@ -2471,11 +2497,12 @@
>  @code{import_module} or @code{use_module} declaration should be in 
>  the implementation section.

I've never understood the way this really works.  What does it mean to
"use" an entity in the interface section?  If a :- pred declaration
mentions a type, do I need to import the module that defines that type
in the interface?  I don't seem to, and I don't understand why.

> -The names of predicates, functions, constructors, types, modes and insts
> -can be explicitly module qualified using the @samp{:} operator,
> -i.e. @samp{module:name}.  This is useful both for readability and
> -for resolving name conflicts.  Uses of entities imported using 
> - at code{use_module} declarations @emph{must} be explicitly module qualified.
> +The names of predicates, functions, constructors, types, modes, insts,

and type classes?  If not, you should mention that and explain why not.

> +and (sub-)modules can be explicitly module qualified using the @samp{:}
> +operator, e.g. @samp{module:name} or @samp{module:submodule:name}.

What about @samp{:module:submodule:name}?  Some syntax for fully
qualified names is necessary to gain the full advantage of nested
modules.

> +Each of the named sub-modules in a @samp{:- include_module} declaration
> +must be defined in a separate source file.

s/defined/declared and defined/

> +The mapping between module names and source file names is
> +implementation-defined.  (The University of Melbourne Mercury
> +implementation requires a module named @samp{foo:bar:baz} to be
> +located in source file @file{foo.bar.baz.m}.)

This is going to bite you someday, whether due to filename length
limits on some unices, or braindead DOS 8.3 restrictions, or limits on
the number of `.' characters in a file name.  And, as I argued before,
a switch in the Mmakefile isn't the right place for this information,
either.

> +The separate source source must contain the definition of

s/source source/source file/

> +If a @samp{:- include_module} declaration occurs in the interface
> +section of a module, then only the interfaces of the sub-modules
> +are included in the parent module's interface; the implementations
> +of the sub-modules are considered to be implicitly part of the
> +parent module's implementation.

Is it permitted for a *nested* submodule in the interface section of a
module to have an implementation section there, too?

> +Apart from that, the semantics of separate sub-modules are
> +identical to those of nested sub-modules.
> +
> + at node Visibility rules
> + at subsection Visibility rules
> +
> +Any declarations in the parent module, including those in the
> +parent module's implementation section, are visible in the parent's
> +sub-modules, including indirect sub-modules (i.e. sub-sub-modules, etc.).
> +Similarly, declarations in the interfaces of any modules imported using a
> + at samp{:- import_module} or a @samp{:- use_module} in the parent module
> +are visible in the parent's sub-modules, including indirect sub-modules.
> +However, declarations in a child module are not visible in the parent
> +module or in "sibling" modules (other children of the same parent)
> +unless the child is explicitly imported using a @samp{:- import_module}
> +or @samp{:- use_module} declaration.

So a module must both include and use a separate submodule in order to
have access to its contents?  Now I'm confused, and this is important.
I think you had better spell out the visibility rules, and give some
examples, too.


-Peter Schachte			| One never notices what has been done; one
pets at cs.mu.OZ.AU		| can only see what remains to be done.
http://www.cs.mu.oz.au/~pets/	| -- Marie Curie 
PGP key available on request	|