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

[Mark Brown]

On Tue, Sep 9, 2014 at 11:59 PM, Zoltan Somogyi
<zoltan.somogyi at runbox.com> wrote:
>
>
> On Tue, 9 Sep 2014 21:20:48 +1000, Mark Brown <mark at mercurylang.org> wrote:
>> > My only issue with (1) is that while it's fine for short messages, it's
>> > going to get a bit messy for longer ones.
>>
>> I think it's a lot to ask that users write consistent error messages.
>
> 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.

>
>> Looking through a recent version of the library, there seems to be two
>> main cases for pragma obsolete: where a predicate or function is
>> replaced by something with identical semantics, and where it is
>> superseded by something with better semantics. Perhaps the pragmas
>> could be written with optional attributes covering these cases?
>> Name/arity references could then use the same syntax as in the first
>> argument. For example:
>>
>> :- pragma obsolete(hash_table.new/3, [replaced_by(hash_table.init/3)]).
>> :- pragma obsolete(string.substring/3, [superseded_by(string.between/3)]).
>>
>> These may well be more informative than the existing library comments
>> (I had to look closely to see that substring was *not* the same as
>> between).
>
> That is actually an argument for the greater flexibility of Julien's original
> proposal: a human-written purpose-specific message could tell you EXACTLY
> what the difference between "between" and "substring" was.

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

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).")
    ]).

Cheers,
Mark.