[m-dev.] proposal: extension to pragma obsolete

[Zoltan Somogyi]

On Wed, 10 Sep 2014 23:31:47 +1000, Mark Brown <mark at mercurylang.org> wrote:
> > If the second argument of the obsolete pragma is optional, as I think
> > it should be, then we are not asking them to; we are merely giving them
> > the ability to do so, if they wish.
> 
> The emphasis is on consistent. In particular, two library authors
> might not mean the same thing when they say "Please use XXX instead";
> it could be read as saying that the names are equivalent, or not.

Now that I see what you mean, I agree. I think what we want is
the best of what you and Julien are proposing: (a) making it compulsory
to say whether the obsolete predicate/function/module has a replacement,
and if yes, whether it has the same semantics, but also (b) making it
possible to expand on that using a message that the writer of
the pragma can control.

> I see no reason to think people will leave better messages in pragmas
> than they do in comments.

I agree, but we can hope :-)

> My proposal:
> (a) is easy to use
> (b) is easy to implement and maintain (compared to (3), at least)
> (c) answers the two most important questions for somebody porting
> obsolete code, namely
>     - What are the replacement predicates/functions/types, if any?
>     - Is a replacement just a name change, or is there a semantic
> difference as well?
> If the difference is semantic, the user will know that they need to
> consult the documentation (or their lab instructor :-().
> 
> If the more general case is really wanted, 'comment' and
> 'verbose_comment' attributes could be added. For example:
> 
> :- pragma obsolete(string.substring/3, [
>         superseded_by(string.between/3),
>         comment("The new string operations were introduced to help
> provide better Unicode support."),
>         verbose_comment("If Start + Count = End then substring(String,
> Start, Count) = between(String, Start, End).")
>     ]).

I like this, but I would prefer one change. As you argue, I think
there should be a second argument that expresses one of three things:

(a) there is no replacement for the obsolete entity
(b) there is a direct, semantically identical replacement for the obsolete entity
(c) there is a direct, but semantically different replacement

(b) and (c) would be accompanied by the name of the replacement.

This argument would be optional overall (for backward compatibility),
but would be required if the user wanted to add the third argument,
which would be a general message (string or list of format components),
as per Julien's original proposal. When the pragma is triggered,
this message would be printed AFTER a message that the compiler
would derive from the second argument.

I think this design approach handles all the concerns we have identified
so far.

Zoltan.