deprecate using codes to identify image tags

Changes

@@ -1,5 +1,11 @@
 Imager release history.  Older releases can be found in Changes.old
 
+ - deprecate setting/deleting tags by code.  If this causes you a
+   problem please open an issue.  You can disable the warning produced
+   with:
+
+    no warnings 'Imager::tagcodes';
+
 Imager 1.015 - 7 May 2022
 ============
 

Imager.pm

@@ -7,6 +7,7 @@ use Imager::Color;
 use Imager::Color::Float;
 use Imager::Font;
 use Imager::TrimColorList;
+use warnings::register qw(tagcodes);
 
 our $ERRSTR;
 
@@ -1420,6 +1421,7 @@ sub addtag {
     }
   }
   elsif ($opts{code}) {
+    warnings::warnif_at_level("Imager::tagcodes", 0, "addtag: code parameter is deprecated");
     if (defined $opts{value}) {
       if ($opts{value} =~ /^\d+$/) {
         # add as a number
@@ -1457,6 +1459,7 @@ sub deltag {
     return i_tags_delbyname($self->{IMG}, $opts{name});
   }
   elsif (defined $opts{code}) {
+    warnings::warnif_at_level("Imager::tagcodes", 0, "deltag: code parameter is deprecated");
     return i_tags_delbycode($self->{IMG}, $opts{code});
   }
   else {
@@ -1476,6 +1479,8 @@ sub settag {
     return $self->addtag(name=>$opts{name}, value=>$opts{value});
   }
   elsif (defined $opts{code}) {
+    warnings::warnif_at_level("Imager::tagcodes", 0, "settag: code parameter is deprecated");
+    no warnings 'Imager::tagcodes';
     $self->deltag(code=>$opts{code});
     return $self->addtag(code=>$opts{code}, value=>$opts{value});
   }

imdatatypes.h

@@ -177,8 +177,8 @@ typedef enum {
 } i_img_bits_t;
 
 typedef struct {
-  char *name; /* name of a given tag, might be NULL */
-  int code; /* number of a given tag, -1 if it has no meaning */
+  char *name; /* name of a given tag */
+  int code; /* number of a given tag, deprecated */
   char *data; /* value of a given tag if it's not an int, may be NULL */
   int size; /* size of the data */
   int idata; /* value of a given tag if data is NULL */

lib/Imager/ImageTypes.pod

@@ -870,6 +870,9 @@ or by code:
 
   my $index = $img->addtag(code=>$code, value=>$value);
 
+Setting tags by C<code> is deprecated.  If you have a use for this
+please open an issue.
+
 =item deltag()
 
 You can remove tags with the deltag() method, either by index:
@@ -886,6 +889,9 @@ or by code:
 
 In each case deltag() returns the number of tags deleted.
 
+Setting or deleting tags by C<code> is deprecated.  If you have a use
+for this please open an issue.
+
 =item settag()
 
 settag() replaces any existing tags with a new tag.  This is

t/100-base/010-introvert.t

@@ -3,9 +3,10 @@
 # to make sure we get expected values
 
 use strict;
-use Test::More tests => 492;
+use Test::More;
 
 BEGIN { use_ok(Imager => qw(:handy :all)) }
+use warnings;
 
 use Imager::Test qw(image_bounds_checks is_color3 is_color4 is_fcolor4 color_cmp mask_tests is_fcolor3);
 
@@ -1132,6 +1133,37 @@ my $psamp_outside_error = "Image position outside of image";
      "check error message");
 }
 
+{
+  # warnings should be enabled
+  my @warn;
+  local $SIG{__WARN__} = sub { push @warn, "@_"; };
+  my $im = Imager->new(xsize => 1, ysize => 1);
+  $im->settag(code => 10, value => 10);
+  is(scalar @warn, 1, "settag with code warns");
+  like($warn[0], qr/settag: code parameter is deprecated/,
+       "check message for settag");
+  @warn = ();
+  {
+    no warnings 'Imager::tagcodes';
+    $im->settag(code => 10, value => 10);
+  }
+  is(scalar @warn, 0, "settag with code with warning disabled doesn't warn");
+
+  @warn = ();
+  $im->addtag(code => 11, value => 11);
+  is(scalar @warn, 1, "addtag with code warns");
+  like($warn[0], qr/addtag: code parameter is deprecated/,
+       "check message for addtag");
+
+  @warn = ();
+  {
+    no warnings 'Imager::tagcodes';
+    $im->addtag(code => 12, value => 12);
+  }
+  is(scalar @warn, 0, "addtag with code with warning disabled doesn't warn");
+
+}
+
 {
   my @tests =
     (
@@ -1151,6 +1183,8 @@ my $psamp_outside_error = "Image position outside of image";
   }
 }
 
+done_testing();
+
 Imager->close_log();
 
 unless ($ENV{IMAGER_KEEP_FILES}) {