[m-rev.] for review: announce deprecations in the term module

[Julien Fischer]

For review by anyone.

The request for review is more an opportunity for people to object
to the uncommenting of the obsolete pragmas in the term module.
On balance, I think it is worth us uncommenting them now in order
to promote the use of the replacements in the next release.

Julien.

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

Announce deprecations in the term module.

Announce replacements for the above.

Uncomment the obsolete pragmas for the deprecated predicates.

NEWS:
library/term.m:
    As above.


diff --git a/NEWS b/NEWS
index ea4d00b..806ea72 100644
--- a/NEWS
+++ b/NEWS
@@ -859,6 +859,22 @@ Changes to the Mercury standard library
      - `int{8,16,32,64}_to_decimal_term/2`
      - `uint_to_decimal_term/2`
      - `uint{8,16,32,64}_to_decimal_term/2`
+    - `rename_var_in_term/4`
+    - `rename_vars_in_terms/4`
+    - `apply_renaming_in_term/3`
+    - `apply_renaming_in_terms/3`
+    - `apply_renaming_in_var/3`
+    - `apply_renaming_in_vars/3`
+    - `apply_renaming_in_term/3`
+    - `apply_renaming_in_terms/3`
+    - `substitute_var_in_term/4`
+    - `substitute_var_in_terms/4`
+    - `substitute_corresponding_in_term/4`
+    - `substitute_corresponding_in_terms/4`
+    - `apply_substitution_in_term/3`
+    - `apply_substitution_in_terms/3`
+    - `apply_rec_substitution_in_term/3`
+    - `apply_rec_substitution_in_terms/3`

  * The following predicates and functions have been moved to the
    `term_conversion` module:
@@ -869,6 +885,29 @@ Changes to the Mercury standard library
     - `type_to_term/[12]`
     - `univ_to_term/[12]`

+* The following predicates and functions have been deprecated and will be
+  removed in a future release:
+
+   - `var_id/1`
+   - `relabel_variable/[34]`
+   - `relabel_variables/[34]`
+   - `rename/[34]`
+   - `rename_list/[34]`
+   - `apply_renaming/[23]`
+   - `apply_renaming_to_list/[23]`
+   - `apply_variable_renaming_to_var/[23]`
+   - `apply_variable_renaming_to_vars/[23]`
+   - `apply_variable_renaming/[23]`
+   - `apply_variable_renaming_to_list/[23]`
+   - `substitute/[34]`
+   - `substitute_list/[34]`
+   - `substitute_corresponding/[34]`
+   - `substitute_corresponding_list/[34]`
+   - `apply_substitution/[23]`
+   - `apply_substitution_to_list/[23]`
+   - `apply_rec_substitution/[23]`
+   - `apply_rec_substitution_to_list/[23]`
+
  ### Changes to the `thread` module

  * The following predicates have been added:
diff --git a/library/term.m b/library/term.m
index 823cc44..3bd0fa5 100644
--- a/library/term.m
+++ b/library/term.m
@@ -134,7 +134,7 @@
      % Obsolete; please use var_to_int instead.
      %
  :- func var_id(var(T)) = int.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(var_id/1).
+:- pragma obsolete(var_id/1, [var_to_int/1]).

  %---------------------------------------------------------------------------%

@@ -327,8 +327,8 @@
  :- func relabel_variable(term(T), var(T), var(T)) = term(T).
  :- pred relabel_variable(term(T)::in, var(T)::in, var(T)::in, term(T)::out)
      is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(relabel_variable/3).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(relabel_variable/4).
+:- pragma obsolete(relabel_variable/3, [rename_var_in_term/4]).
+:- pragma obsolete(relabel_variable/4, [rename_var_in_term/4]).

      % relabel_variables(Terms0, Var, ReplacementVar, Terms):
      %
@@ -340,8 +340,8 @@
  :- func relabel_variables(list(term(T)), var(T), var(T)) = list(term(T)).
  :- pred relabel_variables(list(term(T))::in, var(T)::in, var(T)::in,
      list(term(T))::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(relabel_variables/3).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(relabel_variables/4).
+:- pragma obsolete(relabel_variables/3, [rename_vars_in_terms/4]).
+:- pragma obsolete(relabel_variables/4, [rename_vars_in_terms/4]).

  %---------------------%

@@ -354,8 +354,8 @@
      %
  :- func rename(term(T), var(T), var(T)) = term(T).
  :- pred rename(term(T)::in, var(T)::in, var(T)::in, term(T)::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(rename/3).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(rename/4).
+:- pragma obsolete(rename/3, [rename_var_in_term/4]).
+:- pragma obsolete(rename/4, [rename_var_in_term/4]).

      % rename_list(Terms0, Var, ReplacementVar, Terms):
      %
@@ -367,8 +367,8 @@
  :- func rename_list(list(term(T)), var(T), var(T)) = list(term(T)).
  :- pred rename_list(list(term(T))::in, var(T)::in, var(T)::in,
      list(term(T))::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(rename_list/3).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(rename_list/4).
+:- pragma obsolete(rename_list/3, [rename_var_in_terms/4]).
+:- pragma obsolete(rename_list/4, [rename_var_in_terms/4]).

  %---------------------%

@@ -402,8 +402,8 @@
      %
  :- func apply_renaming(term(T), renaming(T)) = term(T).
  :- pred apply_renaming(term(T)::in, renaming(T)::in, term(T)::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_renaming/2).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_renaming/3).
+:- pragma obsolete(apply_renaming/2, [apply_renaming_in_term/3]).
+:- pragma obsolete(apply_renaming/3, [apply_renaming_in_term/3]).

      % As above, except applies to a list of terms rather than a single term.
      %
@@ -412,8 +412,8 @@
  :- func apply_renaming_to_list(list(term(T)), renaming(T)) = list(term(T)).
  :- pred apply_renaming_to_list(list(term(T))::in, renaming(T)::in,
      list(term(T))::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_renaming_to_list/2).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_renaming_to_list/3).
+:- pragma obsolete(apply_renaming_to_list/2, [apply_renaming_in_terms/3]).
+:- pragma obsolete(apply_renaming_to_list/3, [apply_renaming_in_terms/3]).

  %---------------------%

@@ -424,8 +424,10 @@
  :- func apply_variable_renaming_to_var(renaming(T), var(T)) = var(T).
  :- pred apply_variable_renaming_to_var(renaming(T)::in,
      var(T)::in, var(T)::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_variable_renaming_to_var/2).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_variable_renaming_to_var/3).
+:- pragma obsolete(apply_variable_renaming_to_var/2,
+    [apply_renaming_in_var/3]).
+:- pragma obsolete(apply_variable_renaming_to_var/3,
+    [apply_renaming_in_var/3]).

      % Applies apply_variable_renaming to a list of vars.
      %
@@ -435,8 +437,10 @@
      list(var(T))) = list(var(T)).
  :- pred apply_variable_renaming_to_vars(renaming(T)::in,
      list(var(T))::in, list(var(T))::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_variable_renaming_to_vars/2).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_variable_renaming_to_vars/3).
+:- pragma obsolete(apply_variable_renaming_to_vars/2,
+    [apply_renaming_in_vars/3]).
+:- pragma obsolete(apply_variable_renaming_to_vars/3,
+    [apply_renaming_in_vars/3]).

      % Same as relabel_variable, except relabels multiple variables.
      % If a variable is not in the map, it is not replaced.
@@ -446,8 +450,8 @@
  :- func apply_variable_renaming(term(T), renaming(T)) = term(T).
  :- pred apply_variable_renaming(term(T)::in, renaming(T)::in,
      term(T)::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_variable_renaming/2).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_variable_renaming/3).
+:- pragma obsolete(apply_variable_renaming/2, [apply_renaming_in_term/3]).
+:- pragma obsolete(apply_variable_renaming/3, [apply_renaming_in_term/3]).

      % Applies apply_variable_renaming to a list of terms.
      %
@@ -457,8 +461,10 @@
      list(term(T)).
  :- pred apply_variable_renaming_to_list(list(term(T))::in, renaming(T)::in,
      list(term(T))::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_variable_renaming_to_list/2).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_variable_renaming_to_list/3).
+:- pragma obsolete(apply_variable_renaming_to_list/2,
+    [apply_renaming_in_terms/3]).
+:- pragma obsolete(apply_variable_renaming_to_list/3,
+    [apply_renaming_in_terms/3]).

  %---------------------%

@@ -505,8 +511,8 @@
      %
  :- func substitute(term(T), var(T), term(T)) = term(T).
  :- pred substitute(term(T)::in, var(T)::in, term(T)::in, term(T)::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(substitute/3).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(substitute/4).
+:- pragma obsolete(substitute/3, [substitute_var_in_term/4]).
+:- pragma obsolete(substitute/4, [substitute_var_in_term/4]).

      % substitute_list(Var, ReplacementTerm, Terms0, Terms):
      %
@@ -518,8 +524,8 @@
  :- func substitute_list(list(term(T)), var(T), term(T)) = list(term(T)).
  :- pred substitute_list(list(term(T))::in, var(T)::in, term(T)::in,
      list(term(T))::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(substitute_list/3).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(substitute_list/4).
+:- pragma obsolete(substitute_list/3, [substitute_var_in_terms/4]).
+:- pragma obsolete(substitute_list/4, [substitute_var_in_terms/4]).

      % substitute_corresponding(Vars, ReplacementTerms, Term0, Term):
      %
@@ -534,8 +540,10 @@
      term(T)) = term(T).
  :- pred substitute_corresponding(list(var(T))::in, list(term(T))::in,
      term(T)::in, term(T)::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(substitute_corresponding/3).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(substitute_corresponding/4).
+:- pragma obsolete(substitute_corresponding/3,
+    [substitute_corresponding_in_term/4]).
+:- pragma obsolete(substitute_corresponding/4,
+    [substitute_corresponding_in_term/4]).

      % substitute_corresponding_list(Vars, ReplacementTerms, Terms0, Terms):
      %
@@ -550,8 +558,10 @@
      list(term(T))) = list(term(T)).
  :- pred substitute_corresponding_list(list(var(T))::in, list(term(T))::in,
      list(term(T))::in, list(term(T))::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(substitute_corresponding_list/3).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(substitute_corresponding_list/4).
+:- pragma obsolete(substitute_corresponding_list/3,
+    [substitute_corresponding_in_terms/4]).
+:- pragma obsolete(substitute_corresponding_list/4,
+    [substitute_corresponding_in_terms/4]).

  %---------------------%

@@ -606,8 +616,10 @@
  :- func apply_substitution(term(T), substitution(T)) = term(T).
  :- pred apply_substitution(term(T)::in, substitution(T)::in,
      term(T)::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_substitution/2).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_substitution/3).
+:- pragma obsolete(apply_substitution/2,
+    [apply_substitution_in_term/3]).
+:- pragma obsolete(apply_substitution/3,
+    [apply_substitution_in_term/3]).

      % apply_substitution_to_list(Term0, Substitution, Term):
      %
@@ -619,8 +631,10 @@
      list(term(T)).
  :- pred apply_substitution_to_list(list(term(T))::in, substitution(T)::in,
      list(term(T))::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_substitution_to_list/2).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_substitution_to_list/3).
+:- pragma obsolete(apply_substitution_to_list/2,
+    [apply_substitution_in_terms/3]).
+:- pragma obsolete(apply_substitution_to_list/3,
+    [apply_substitution_in_terms/3]).

      % apply_rec_substitution(Term0, Substitution, Term):
      %
@@ -632,8 +646,10 @@
  :- func apply_rec_substitution(term(T), substitution(T)) = term(T).
  :- pred apply_rec_substitution(term(T)::in, substitution(T)::in,
      term(T)::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_rec_substitution/2).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_rec_substitution/3).
+:- pragma obsolete(apply_rec_substitution/2,
+    [apply_rec_substitution_in_term/3]).
+:- pragma obsolete(apply_rec_substitution/3,
+    [apply_rec_substitution_in_term/3]).

      % apply_rec_substitution_to_list(Terms0, Substitution, Terms):
      %
@@ -646,8 +662,10 @@
      list(term(T)).
  :- pred apply_rec_substitution_to_list(list(term(T))::in, substitution(T)::in,
      list(term(T))::out) is det.
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_rec_substitution_to_list/2).
-% NOTE_TO_IMPLEMENTORS :- pragma obsolete(apply_rec_substitution_to_list/3).
+:- pragma obsolete(apply_rec_substitution_to_list/2,
+    [apply_rec_substitution_in_terms/3]).
+:- pragma obsolete(apply_rec_substitution_to_list/3,
+    [apply_rec_substitution_in_terms/3]).

  %---------------------%