for review: add nested modules [5/5]

[Fergus Henderson]

On 04-Mar-1998, Peter Schachte <pets at students.cs.mu.OZ.AU> wrote:
> 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./

If they were declared in different modules, they'd be different predicates.

If I were to add "in the same module", for clarity, then
I'd have to add "with the same name and arity" too.
And then it would look quite ugly.  I think the current wording
is clear enough.

> +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 implementation lets you get away with some stuff that the
language reference manual doesn't condone.

> > +The interface section can contain declarations or definitions of types,
> 
> insert `and' or `as well as' here.

I'll rephrase that whole sentence.

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

It's pronounced "a colon-dash implementation declaration".

> > +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/

I think DJ already picked that one up.

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

This section describes what constitutes a valid module.
Anything not explicitly allowed is implicitly disallowed.
I don't think it's necessary to spell this out explicitly.

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

But then people might use it...

Currently it is a feature supported by the implementation,
which we are using in the compiler so that we can get some
experience with it before deciding whether to include it
in the language.

Hence the "no".

> >  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?

If/when we add support for a leading ":" in module names,
then we should revisit the use of the term "fully-qualified" here.

> > @@ -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?

Yes.

> I don't seem to, and I don't understand why.

That was a bug in the implementation, which this change fixed.
(We used to get it right, I think, but there was a regression
about a year ago.)

I committed the change this morning, so it should be installed overnight.

Note that we still don't report errors if you use the fully-qualified
type name.  This is another bug, but one that is difficult to fix.

> > -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?

Yes.

> > +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}?

Not supported (yet).

> > +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/

Hmm, there is a problem here, but your suggested fix raises
more questions than it answers...  I'll see what I can do.

> > +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. 

Implementations on OSs which don't support such file names
can use different file naming conventions, or can (for example)
allow the user to provide a file containing the mapping between
module names and source files.

> And, as I argued before,
> a switch in the Mmakefile isn't the right place for this information,
> either.

?  Why not?

You argued that it might be bad if we allowed the `:- module'
declaration for separate sub-modules to be not fully-qualified
(as is currently the status quo).
I agree allowing this does, in combination with the implicit import
of the parent's private interface, could have some potentially bad
effects on readability --- in particular, if the user can't easily
figure out a module's fully-qualified name when reading it, then
he can't tell which parent modules it implicitly imports.
But that's a separate issue.

> > +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?

No.  Here's the relevant quotes from the reference manual:

	If a nested sub-module declaration includes an interface section,
	then it is a declaration of that sub-module;
	if it includes an implementation section,
	then it is a definition of that sub-module;

	The interface section may not contain definitions for functions or
	predicates (i.e. clauses), or definitions of (sub-)modules. 

Isn't that sufficiently clear?

> > +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?

Yep.

> Now I'm confused

Probably because I made a subtle change between the original proposal
and the above: nested sub-modules are not implicitly "used" in the
parent module.

> I think you had better spell out the visibility rules, and give some
> examples, too.

It is spelt out above.  I think the description there is clear.
(You managed to figure it out, even despite being confused by
a subly different previous proposal ;-)
Some examples could help, I guess...


I'll post a new diff shortly.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>   |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>   |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3         |     -- the last words of T. S. Garp.