[m-rev.] for review: rewrite of Modes chapter

[Fergus Henderson]

Thanks Mark, that looks like a big improvement!
I have a lot of detailed comments, but overall I think it is very good.

On 20-Feb-2003, Mark Brown <dougl at cs.mu.OZ.AU> wrote:
> +In Mercury, the state of instantiation, or @dfn{inst}, of a variable
> +is a description of the terms that the variable may be bound to.

Hmm.  I'm not very comfortable with the use of the phrase "may be
bound to" here, since it should also include the case when the variable
is unbound.

Perhaps "may hold" instead of "may be bound to"??

> +The @dfn{mode} of a predicate or function
> +describes how the inst of each argument and return value (if there is one)
> +changes between a call to that predicate or function and an exit from it.

This wording is a big ambiguous, because "exit" could include failure.

I suggest

	The @dfn{mode} of a predicate or function describes the inst
	which each argument and return value (if there is one) may have
	when the predicate or function is called, and the corresponding
	inst that each will have if the predicate or function succeeds.

> +Mercury allows the user to specify modes directly
>  by expressions such as @code{inst1 >> inst2},

s/inst1/@var{inst1}/
s/inst2/@var{inst2}/

>  or to give them a name using declarations such as
>  
> @@ -2178,6 +2112,10 @@
>  :- mode m == inst1 >> inst2.
>  @end example
>  
> + at noindent

I suggest adding "and then refer to them by name." here.

> +There must not be more than one mode definition
> +with the same name and arity in the same module.
> +
>  It is also possible to write mode declarations using @code{::}
>  and @code{->} instead of @code{==} and @code{>>} respectively,
>  however this syntax is deprecated and may not be supported in future.
> @@ -2190,6 +2128,7 @@
>  :- mode out == free >> ground.
>  @end example
>  
> + at noindent
>  Prolog fans who want to use the symbols @samp{+} and @samp{-}
>  can do so by simply defining them using a mode declaration:

The @noindent there is wrong; this is a new paragraph.

> + at noindent
> +If any argument or return value in such a declaration
> +is of the form @samp{type::mode}, then all of them must be.

s/type/@var{type}/
s/mode/@var{mode}/

> @@ -2409,6 +2274,8 @@
>  with respect to a given mode declaration}
>  if given that the predicates and functions called by @var{p}
>  all satisfy their mode declaration constraints,
> +and given that @var{p} is called with argument terms that are
> +described by the initial insts of the mode declaration,
>  there exists an ordering of the conjuncts in each conjunction
>  in the clauses of @var{p} such that

Yes, that looks correct.

> @@ -2436,24 +2303,177 @@
>  it reports an error if no satisfactory order exists.
>  Finally it checks that
>  the resulting instantiatedness of the procedure's arguments
> -is the same as the one given by the procedure's declaration.
> +matches the one given by the procedure's declaration.
> +For the simple insts we have seen so for,
> +the word ``matches'' just means ``is the same as'';
> +we will extend this definition as new insts are introduced.

Didn't you introduce user-defined insts already?
If so, insts should match if they are the same after
all user-defined insts have been replaced with their bodies.

>  The mode analysis algorithm annotates each call with the mode used.
>  
> +
> + at node Insts defined using bound
> + at section Insts defined using @samp{bound}

I suggest that this section be titled "Structured insts".
(Or perhaps "Subtype insts".  But I think "Structure insts" is better.)

> + at node Uniqueness ordering
> + at section Uniqueness ordering
...
> +For inst @var{A} to be more instantiated than inst @var{B},
> +it is necessary that @var{A} be of equal or less uniqueness than @var{B}
> +according to the above ordering,
> +in addition to the rules that apply for the corresponding
> + at code{free}, @code{ground} and @code{bound} insts.
> +
> +For inst @var{A} to match inst @var{B},
> +the uniqueness ordering is reversed:
> +it is necessary that @var{A} be of equal or greater uniqueness than @var{B}
> +according to the above ordering,
> +in addition to the rules that apply for the corresponding
> + at code{free}, @code{ground} and @code{bound} insts.

s/the uniqueness ordering/the uniqueness ordering condition/

(I found the thought of reversing the uniquess ordering confusing...
``now, let time run backwards...'' :-)

> +Note that since the ordering is reversed,

s/ordering/ordering condition/

> +A higher-order inst @var{A} is at least as instantiated as inst @var{B} iff
> + at var{A} is identical to @var{B}.
> +Higher-order terms are considered ground,
> +and there is no way for them to become more ground.

I think this is wrong.  The "is at least as instantiated as" ordering
should be the same as the "matches" ordering for higher-order insts.

The compiler is currently still broken regarding this; see
<http://www.cs.mu.oz.au/research/mercury/mailing-lists/mercury-reviews/
mercury-reviews.0211/0325.html>.

Also, it should say somewhere that higher-order terms are at least
as instantiated as "ground", but "ground" is not as instantiated
as any higher-order term.

Likewise, there should be a description of when "ground" is considered
at least as instantiated as a subtype inst and vice versa.


Otherwise, that looks good.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------