Improve obsolete to support multiple levels

Obsolete warnings of level 1 will be displayed by default.
Obsolete declarations taken an optional argument to set obsolete
level (which defaults to 2).
Obsolete warnings are now only printed once per obsolete function.

doc/ref/obsolete.xml

@@ -199,13 +199,16 @@ Note that <C>MultRowVector</C> was also renamed to <C>MultVectorLeft</C>.
 <InfoClass Name="InfoObsolete"/>
 <Description>
 is an info class to display warnings when an obsolete variable is used.
-By default, these warnings are switched off since the info level for 
-this class is 0. Setting it to 1 will trigger warnings if &GAP; will 
-detect that an obsolete variable is used at runtime.
+By default, the info level for this class is set to 1, which will only
+show variables which will be removed in the next major version of GAP.
+Setting it to 2 will trigger further warnings, for variables which have
+alternative names, or may be removed in future.
+
+This class can be set to 0 to disable all obsolete warnings.
 <P/>
-To check that the &GAP; code does not use obsolete variables at the 
-parsing time, and not at a runtime, use <C>-O</C> command line option,
-see <Ref Sect="Command Line Options"/>. 
+To check that the &GAP; code does not use any obsolete variables at
+parsing time, and not at a runtime, use the <C>-O</C> command line option,
+see <Ref Sect="Command Line Options"/>.
 </Description>
 </ManSection>
 

lib/info.gi

@@ -429,8 +429,9 @@ end);
 ##
 #V  InfoObsolete
 ##
-##  This info class has a default level of 0.
-##  Warnings can be switched on by setting its level to one.
+##  This info class has a default level of 1.
+##  Warnings can be disabled entirely by setting its level to 0, and further
+##  warnings can be switched on by setting its level to 2.
 ##
 DeclareInfoClass( "InfoObsolete" );
-SetInfoLevel(InfoObsolete,0);
+SetInfoLevel(InfoObsolete,1);

lib/obsolete.gd

@@ -55,6 +55,17 @@
 ##  Usually, old names will be available for several releases;
 ##  they may be removed when they don't seem to be used any more.
 ##  <P/>
+##  Information about obsolete names is printed by <Ref Func="Info"/> using the
+##  InfoObsolete Info class. By default InfoObsolete is set to 1. Newly
+##  obsoleted identifiers should at first be outputted at info level 2. Once they
+##  have been removed from all packages, they should then be moved to info level
+##  1, so they are visible to normal users, for at least one major release before
+##  being removed.
+##  <P/>
+##  The functions DeclareObsoleteSynonym and DeclareObsoleteSynonymAttr take
+##  an optional final paremeter, specifying the info level at which the given
+##  obsolete symbol should be reported. It defaults to 1.
+##  <P/>
 ##  The obsolete &GAP; code is collected in two library files,
 ##  <F>lib/obsolete.gd</F> and <F>lib/obsolete.gi</F>.
 ##  By default, these files are read when &GAP; is started.
@@ -76,19 +87,29 @@
 ##  <#/GAPDoc>
 ##
 
-BIND_GLOBAL( "DeclareObsoleteSynonym", function( name_obsolete, name_current )
-    local value, orig_value;
+BIND_GLOBAL( "DeclareObsoleteSynonym", function( name_obsolete, name_current, level_arg... )
+    local value, orig_value, printed_warning, level;
     if not ForAll( [ name_obsolete, name_current ], IsString ) then
         Error("Each argument of DeclareObsoleteSynonym must be a string\n");
     fi;
+    if Length(level_arg) = 0 then
+        level := 2;
+    else
+        level := level_arg[1];
+    fi;
+
     value := EvalString( name_current );
     if IsFunction( value ) then
         orig_value := value;
+        printed_warning := false;
         value := function (arg)
             local res;
-            Info( InfoObsolete, 1, "'", name_obsolete, "' is obsolete.",
-                "\n#I  It may be removed in a future release of GAP.",
-                "\n#I  Use ", name_current, " instead.");
+            if not printed_warning and InfoLevel(InfoObsolete) >= level then
+                Info( InfoObsolete, level, "'", name_obsolete, "' is obsolete.",
+                    "\n#I  It may be removed in a future release of GAP.",
+                    "\n#I  Use ", name_current, " instead.");
+                printed_warning := true;
+            fi;
             # TODO: This will error out if orig_value is a function which returns nothing.
             #return CallFuncList(orig_value, arg);
             res := CallFuncListWrap(orig_value, arg);
@@ -100,11 +121,16 @@ BIND_GLOBAL( "DeclareObsoleteSynonym", function( name_obsolete, name_current )
     BIND_GLOBAL( name_obsolete, value );
 end );
 
-BIND_GLOBAL( "DeclareObsoleteSynonymAttr", function( name_obsolete, name_current )
+BIND_GLOBAL( "DeclareObsoleteSynonymAttr", function( name_obsolete, name_current, level_arg... )
+    local level;
     Assert(0, IsFunction( ValueGlobal( name_current ) ) );
-    DeclareObsoleteSynonym( name_obsolete, name_current );
-    DeclareObsoleteSynonym( Concatenation("Set", name_obsolete), Concatenation("Set", name_current) );
-    DeclareObsoleteSynonym( Concatenation("Has", name_obsolete), Concatenation("Has", name_current) );
+    level := 1;
+    if Length(level_arg) > 0 then
+        level := level_arg[1];
+    fi;
+    DeclareObsoleteSynonym( name_obsolete, name_current, level );
+    DeclareObsoleteSynonym( Concatenation("Set", name_obsolete), Concatenation("Set", name_current), level );
+    DeclareObsoleteSynonym( Concatenation("Has", name_obsolete), Concatenation("Has", name_current), level );
 end );
 
 

tst/testbugfix/2013-06-14-t00300.tst

@@ -3,7 +3,7 @@ gap> foo:=function() return 42; end;
 function(  ) ... end
 gap> DeclareObsoleteSynonym("bar","foo");
 gap> oldLevel := InfoLevel(InfoObsolete);;
-gap> SetInfoLevel(InfoObsolete,1);
+gap> SetInfoLevel(InfoObsolete,2);
 gap> bar();
 #I  'bar' is obsolete.
 #I  It may be removed in a future release of GAP.

tst/testinstall/obsolete.tst

@@ -0,0 +1,57 @@
+gap> START_TEST("obsolete.tst");
+gap> newfunc:=function() return 42; end;
+function(  ) ... end
+gap> DeclareObsoleteSynonym("obsoletetestfunc","newfunc",1);
+gap> DeclareObsoleteSynonym("obsoletetestfunc2","newfunc",2);
+gap> DeclareObsoleteSynonym("obsoletetestfunc3","newfunc",2);
+gap> oldLevel := InfoLevel(InfoObsolete);;
+gap> SetInfoLevel(InfoObsolete,1);
+gap> obsoletetestfunc();
+#I  'obsoletetestfunc' is obsolete.
+#I  It may be removed in a future release of GAP.
+#I  Use newfunc instead.
+42
+gap> obsoletetestfunc();
+42
+gap> obsoletetestfunc2();
+42
+gap> obsoletetestfunc2();
+42
+gap> SetInfoLevel(InfoObsolete, 2);
+gap> obsoletetestfunc2();
+#I  'obsoletetestfunc2' is obsolete.
+#I  It may be removed in a future release of GAP.
+#I  Use newfunc instead.
+42
+gap> obsoletetestfunc2();
+42
+gap> obsoletetestfunc3();
+#I  'obsoletetestfunc3' is obsolete.
+#I  It may be removed in a future release of GAP.
+#I  Use newfunc instead.
+42
+gap> obsoletetestfunc3();
+42
+gap> DeclareObsoleteSynonymAttr("obsoleteattr", "IsEmpty");
+gap> obsoleteattr([1,2,3]);
+#I  'obsoleteattr' is obsolete.
+#I  It may be removed in a future release of GAP.
+#I  Use IsEmpty instead.
+false
+gap> obsoleteattr([1,2,3]);
+false
+gap> obsoleteattr([]);
+true
+gap> Hasobsoleteattr([]);
+#I  'Hasobsoleteattr' is obsolete.
+#I  It may be removed in a future release of GAP.
+#I  Use HasIsEmpty instead.
+true
+gap> Hasobsoleteattr([]);
+true
+gap> Setobsoleteattr([], true);
+#I  'Setobsoleteattr' is obsolete.
+#I  It may be removed in a future release of GAP.
+#I  Use SetIsEmpty instead.
+gap> SetInfoLevel(InfoObsolete, oldLevel);
+gap> STOP_TEST("obsolete.tst");