[m-dev.] tightening up require_complete_switch

[Peter Wang]

On Tue, 19 Apr 2016 12:07:06 +1000 (AEST), "Zoltan Somogyi" <zoltan.somogyi at runbox.com> wrote:
> 
> > require_complete_switch is quite prevalent in code outside the compiler
> > so I don't want to advocate a breaking change.  If it were possible to
> > remove the [X] part with a significant transition period, then I would
> > like to see that happen. 
> 
> Why? Don't you find the variable useful documentation? There are some
> disjunctions that can be looked at as switches on *more* than one variable
> (e.g. assoc_list.from_corresponding_lists); I find the variable name slightly
> useful in that it tells me "you don't have to search for another variable
> that this disjunction is a switch on".

Perhaps, only just useful.

> We could in future even use the
> variable name in the scope to control switch detection, by checking
> whether the disjunction it is given is a switch on the named variable
> *before* checking to see if it is a switch on any other variables.
> (In fact, I think this should be easy to implement.)

True.

> > > diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
> > > index ef57532..611093e 100644
> > > --- a/doc/reference_manual.texi
> > > +++ b/doc/reference_manual.texi
> > > @@ -950,15 +950,13 @@ for all the function symbols in the type of @var{Var},
> > >  then @code{require_complete_switch [@var{Var}] @var{Goal}}
> > >  is equivalent to @var{Goal}.
> > >  If @var{Goal} is a switch on @var{Var} but it is not a complete switch,
> > > -i.e. it has no arm
> > > -for at least one of the function symbols in the type of @var{Var},
> > > -then the compiler is required to generate an error message.
> > > +i.e. if some of the function symbols in the type of @var{Var}
> > > +that @var{Var} could be bound to at this point in the code
> > > +are not covered by any arm of the switch,
> > > +then the compiler is required to generate an error message,
> > > +preferably one that lists the uncovered function symbols.
> > 
> > The "preferably one that lists the uncovered function symbols" part is
> > jarring when read from a user's point of view (the main audience), so I
> > suggest deleting it.
> 
> If there is nothing there, then the text would say the same thing, i.e.
> "is required to generate an error message", for both (a) the subgoal
> is a switch on X, but it is not complete, and (b) the subgoal is not
> a switch on X. I was trying to differentiate the two; (a) is the intended
> purpose of the scope, while (b) is just a technicality. Do you not think
> that emphasizing the intended purpose is worthwhile? Do you have
> a better way to do it?

How about this?

require_complete_switch [VAR] GOAL

     A switch completeness check, typically used to enhance the
     robustness of code.

     If GOAL is a switch on VAR and the switch is complete, i.e.
     the switch has an arm for every function symbol that VAR
     could be bound to at this point in the code, then
     `require_complete_switch [VAR] GOAL' is equivalent to GOAL.

     If GOAL is a switch on VAR but is @emph{not} complete, or GOAL is
     not a switch at all, then the compiler is required to generate an
     error message.

I combined the two negative cases into one sentence, but reduced the
complexity of the sentence by deleting the explicit explanation of
incompleteness.  It should be clear from the preceding sentence.
The words "not complete" instead of "incomplete" are intended to
emphasise the connection to the preceding sentence.

(Your diff had the old wording "for all the function symbols in
the type of @var{Var}" in the positive case.)

Peter