diff: phase out term__compare/4

[Fergus Henderson]

This change is in response to a bug report by Paul Massey.

--------------------

Phase out term__compare/4, since it is error-prone (the comparison
includes the term__contexts, which is probably not what you want)
and in general is probably not quite the right interface.
In addition, it's probably not of sufficient usefulness to
warrant inclusion in the standard library -- programmers can always
implement it themselves.

library/term.m:
	Add `pragma obsolete' declaration and some comments for
	term__compare/4, and move the declaration into a separate
	interface section so that it won't appear in the library
	reference manual.

NEWS:
	Mention this change.

Index: NEWS
===================================================================
RCS file: /home/mercury1/repository/mercury/NEWS,v
retrieving revision 1.114
diff -u -r1.114 NEWS
--- NEWS	1998/08/10 07:16:44	1.114
+++ NEWS	1998/09/02 05:14:21
@@ -345,6 +345,10 @@
   unsafe_dump_tableaus/0 in extras/clpr/dump.m; and debug_freeze/3
   and debug_freeze/4 in extras/trailed_update/var.m.
 
+* The interface to the predicate term__compare/4 was found to be error-prone,
+  and so we are phasing it out; it is declared with `pragma obsolete'
+  in this version, so any use of it will now result in a warning, and
+  the predicate will be removed entirely in some future version.
 
 Changes to the Mercury implementation:
 **************************************
Index: library/term.m
===================================================================
RCS file: /home/mercury1/repository/mercury/library/term.m,v
retrieving revision 1.83
diff -u -r1.83 term.m
--- term.m	1998/08/24 04:45:31	1.83
+++ term.m	1998/09/02 04:17:08
@@ -220,15 +220,6 @@
 :- mode term__is_ground(in) is semidet.
 %	term__is_ground(Term) is true iff Term contains no variables.
 
-:- pred term__compare(comparison_result, term, term, substitution).
-:- mode term__compare(out, in, in, in) is semidet.
-%	term__compare(Comparison, Term1, Term2, Bindings) is true iff
-%		there is a binding of Comparison to <, =, or > such
-%		that the binding holds for the two ground terms Term1
-%		and Term2 with respect to the bindings in Bindings.
-%		Fails if Term1 or Term2 is not ground (with respect to
-%		the bindings in Bindings).
-
 %-----------------------------------------------------------------------------%
 
 	% To manage a supply of variables, use the following 2 predicates.
@@ -286,6 +277,31 @@
 :- pred term__var_list_to_term_list(list(var), list(term)).
 :- mode term__var_list_to_term_list(in, out) is det.
 :- mode term__var_list_to_term_list(out, in) is semidet.
+
+%-----------------------------------------------------------------------------%
+
+:- implementation.
+
+% Everything below here is not intended to be part of the public interface,
+% and will not be included in the Mercury library reference manual.
+
+%-----------------------------------------------------------------------------%
+
+:- interface.
+
+	% This predidicate is being phased out, because of the problem
+	% mentioned in the "BEWARE:" below.
+:- pragma obsolete(term__compare/4).
+:- pred term__compare(comparison_result, term, term, substitution).
+:- mode term__compare(out, in, in, in) is semidet.
+%	term__compare(Comparison, Term1, Term2, Bindings) is true iff
+%		there is a binding of Comparison to <, =, or > such
+%		that the binding holds for the two ground terms Term1
+%		and Term2 with respect to the bindings in Bindings.
+%		Fails if Term1 or Term2 is not ground (with respect to
+%		the bindings in Bindings).
+%		BEWARE: the comparison does not ignore the term__contexts
+%		in the terms.
 
 %-----------------------------------------------------------------------------%
 %-----------------------------------------------------------------------------%

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