Add 'delete' mode in attribute update + minor documentation cleaning

lib/Net/Whois/Object.pm

@@ -71,7 +71,7 @@ are strings and no more Net::Whois::Objects.
     # Add a phone number
     $person->phone(' +33 4 88 00 65 15');
 
-Some attributes can have multiple value (remarks, mnt-by...) first implementation allowed only to
+Some attributes can have multiple values (remarks, mnt-by...) first implementation allowed only to
 add one value
 
     # Add one maintener
@@ -89,7 +89,14 @@ Which is a verbose way to do exactly as the default mode above, but also
 Or even
 
     # Replace CPNY-MNT2 by REPL-MNT
-    $person->mnt_by({mode => 'replace', value => {old => 'CPNY-MNT2', old => 'REPL-MNT'}});
+    $person->mnt_by({mode => 'replace', value => {old => 'CPNY-MNT2', new => 'REPL-MNT'}});
+
+From release 2.002 you can also use the 'delete' mode to remove a specific attribute value
+
+    $person->mnt_by({mode => 'delete', value => {old => 'REPL-MNT'}});
+    
+    # Or if you want to remove all remarks (the regex '.' meaning any char, will match all remarks values)
+    $person->remarks({mode => 'delete', value => {old => '.'}});
 
 
 =head2 Dump the current state of the data
@@ -107,7 +114,8 @@ dump() handle the 'align' parameter passed though a hash ref.
 =head2 Update the RIPE database
 
 The RIPE database update is currently under heavy development.
-*The update code is to be considered as experimental.*
+
+B<*The update code is still to be considered as experimental.*>
 
 We plan to offer several ways to update the RIPE database
 
@@ -146,7 +154,7 @@ array reference of additional options to pass to the signing binary.
 
 The primary key of the object created is returned.
 The attribute used as primary key can be obtained through 
-$object->attribute('primary') 
+C<$object->attribute('primary')>
 
 =head4 Update
 
@@ -277,7 +285,7 @@ sub new {
 
     }
 
-    # TODO : fix the trailing undef
+    # TODO: fix the trailing undef
     return grep {defined} @results;
 }
 
@@ -326,7 +334,7 @@ sub clone {
 =head2 B<attributes( [$type [, \@attributes]] )>
 
 Accessor to the attributes of the object. 
-$type can be 
+C<$type> can be 
 
     'primary'   Primary/Lookup key
     'mandatory' Required for update creation
@@ -336,7 +344,7 @@ $type can be
     'all'       You can't specify attributes for this special type
                 which provides all the attributes which have a type
 
-If no $type is specified, 'all' is assumed.
+If no C<$type> is specified, 'all' is assumed.
 Returns a list of attributes of the required type.
 
 =cut
@@ -383,7 +391,7 @@ sub class {
 
 =head2 B<attribute_is ( $attribute, $type )>
 
-This method return true if $attribute is of type $type.
+This method return true if C<$attribute> is of type C<$type>
 
 =cut
 
@@ -426,7 +434,7 @@ sub displayed_attributes {
 Simple naive way to display a text form of the class.
 Try to be as close as possible as the submited text.
 
-Currently the only option available is 'align' which accept a $column number as
+Currently the only option available is 'align' which accept a C<$column> number as
 parameter so that all C<< $self->dump >> produces values that are aligned
 vertically on column C<$column>.
 
@@ -582,10 +590,10 @@ Query the RIPE database and return Net::Whois::Objects
 
 This method accepts 2 optional parameters
 
-'type' which is a regex used to filter the query result :
+'type' which is a regex used to filter the query result:
 Only the object whose type matches the 'type' parameter are returned
 
-'attribute' which is a regex used to filter the query result :
+'attribute' which is a regex used to filter the query result:
 Only the value of the attributes matching the 'attribute' parameter are
 returned
 
@@ -756,6 +764,13 @@ sub _multiple_attribute_setget {
                     $_ = $value->{new} if $_ =~ /$old/;
                 }
             }
+        } elsif ( $mode eq 'delete' ) {
+            if ( ref $value ne 'HASH' or !$value->{old} ) {
+                croak " {old=>...} expected as value for $attribute update in delete mode";
+            } else {
+                my $old = $value->{old};
+                $self->{$attribute} = [grep {!/$old/} @{$self->{$attribute}}];
+            }
         } else {
             croak "Unknown mode $mode for attribute $attribute";
         }

lib/Net/Whois/Object/AsSet.pm

@@ -2,7 +2,7 @@ package Net::Whois::Object::AsSet;
 
 use base qw/Net::Whois::Object/;
 
-# From : whois -t as-set  
+# From: whois -t as-set  
 #
 # % This is the RIPE Database query service.
 # % The objects are in RPSL format.

lib/Net/Whois/Object/AutNum.pm

@@ -2,7 +2,7 @@ package Net::Whois::Object::AutNum;
 
 use base qw/Net::Whois::Object/;
 
-# from : whois -t aut-num
+# from: whois -t aut-num
 # % This is the RIPE Database query service.
 # % The objects are in RPSL format.
 # %

lib/Net/Whois/Object/Inet6Num.pm

@@ -5,7 +5,7 @@ use base qw/Net::Whois::Object/;
 # http://www.ripe.net/data-tools/support/documentation/update-ref-manual#section-12
 # http://www.apnic.net/apnic-info/whois_search/using-whois/guide/inet6num
 #
-# From : whois -t inet6num  
+# From: whois -t inet6num  
 # % This is the RIPE Database query service.
 # % The objects are in RPSL format.
 # %

lib/Net/Whois/Object/InetNum.pm

@@ -5,7 +5,7 @@ use base qw/Net::Whois::Object/;
 # http://www.ripe.net/data-tools/support/documentation/update-ref-manual#section-13
 # http://www.apnic.net/apnic-info/whois_search/using-whois/guide/inetnum
 #
-# From :  whois -t inetnum 
+# From:  whois -t inetnum 
 # % This is the RIPE Database query service.
 # % The objects are in RPSL format.
 # %

lib/Net/Whois/Object/Limerick.pm

@@ -2,7 +2,7 @@ package Net::Whois::Object::Limerick;
 
 use base qw/Net::Whois::Object/;
 
-# RIPE : Deprecated
+# RIPE: Deprecated
 #
 #
 # limerick:      [mandatory]  [single]     [primary/look-up key]

lib/Net/Whois/Object/Organisation.pm

@@ -2,7 +2,7 @@ package Net::Whois::Object::Organisation;
 
 use base qw/Net::Whois::Object/;
 
-# From  : whois -t organisation
+# From: whois -t organisation
 # % This is the RIPE Database query service.
 # % The objects are in RPSL format.
 # %
@@ -77,7 +77,7 @@ Accepts an optional org_name, always return the current org_name.
 Accessor to the org_type attribute.
 Accepts an optional org_type, always return the current org_type.
 
-Possible values are :
+Possible values are:
 IANA for Internet Assigned Numbers Authority, RIR for Regional Internet
 Registries, NIR for National Internet Registries, LIR for Local Internet
 Registries, and OTHER for all other organisations. 

lib/Net/Whois/Object/PeeringSet.pm

@@ -5,7 +5,7 @@ use base qw/Net::Whois::Object/;
 # http://www.ripe.net/data-tools/support/documentation/update-ref-manual#section-19
 # http://www.apnic.net/apnic-info/whois_search/using-whois/guide/peering-set
 #
-# From : whois -t peering-set 
+# From: whois -t peering-set 
 # % This is the RIPE Database query service.
 # % The objects are in RPSL format.
 # %

lib/Net/Whois/Object/Person.pm

@@ -5,7 +5,7 @@ use base qw/Net::Whois::Object/;
 # http://www.ripe.net/data-tools/support/documentation/update-ref-manual#section-20
 # http://www.apnic.net/apnic-info/whois_search/using-whois/guide/person
 #
-# From :  whois -t person
+# From:  whois -t person
 # % This is the RIPE Database query service.
 # % The objects are in RPSL format.
 # %

lib/Net/Whois/Object/Route.pm

@@ -5,7 +5,7 @@ use base qw/Net::Whois::Object/;
 # http://www.ripe.net/data-tools/support/documentation/update-ref-manual#section-25
 # http://www.apnic.net/apnic-info/whois_search/using-whois/guide/route
 #
-# From : whois -t route
+# From: whois -t route
 # % This is the RIPE Database query service.
 # % The objects are in RPSL format.
 # %

lib/Net/Whois/Object/RouteSet.pm

@@ -5,7 +5,7 @@ use base qw/Net::Whois::Object/;
 # http://www.ripe.net/data-tools/support/documentation/update-ref-manual#section-26
 # http://www.apnic.net/apnic-info/whois_search/using-whois/guide/route-set
 #
-# From : whois -t route-set
+# From: whois -t route-set
 # % This is the RIPE Database query service.
 # % The objects are in RPSL format.
 # %

lib/Net/Whois/Object/RtrSet.pm

@@ -5,7 +5,7 @@ use base qw/Net::Whois::Object/;
 # http://www.ripe.net/data-tools/support/documentation/update-ref-manual#section-27
 # http://www.apnic.net/apnic-info/whois_search/using-whois/guide/rtr-set
 #
-# From : whois -t route-set
+# From: whois -t route-set
 # % This is the RIPE Database query service.
 # % The objects are in RPSL format.
 # %

t/03-objects.t

@@ -30,6 +30,9 @@ can_ok $o[5], qw( aut_num as_name org source ), qw( descr member_of import mp_im
     mnt_lower mnt_by mnt_routes changed);
 ok( !$o[5]->can('bogusmethod'), "No AUTOLOAD interference with ${class}::AutNum tests" );
 
+#
+# 'attributes' method
+#
 is_deeply( [ $o[0]->attributes('mandatory') ], ['comment'] );
 
 is_deeply( [ $o[0]->attributes('optional') ], [] );
@@ -39,20 +42,32 @@ is_deeply( [ $o[0]->attributes('optional') ], [ 'opt1', 'opt2', 'opt3' ] );
 is_deeply( [ $o[0]->attributes('all') ], [ 'comment', 'opt1', 'opt2', 'opt3' ] );
 is_deeply( [ $o[0]->attributes() ],      [ 'comment', 'opt1', 'opt2', 'opt3' ] );
 
+#
+# 'dump' method
+#
 is( $o[2]->dump, "% Information related to 'AS30720 - AS30895'\n" );
 is( $o[2]->dump( { align => 8 } ), "% Information related to 'AS30720 - AS30895'\n" );
 
+#
+# 'clone' method
+#
 my $clone = $o[3]->clone;
 isa_ok($clone, ref $o[3], "Clone object has the same type of source");
 is_deeply($clone, $o[3], "Clone object deeply similar to source");
-
 $clone = $o[3]->clone({remove => ['source','remarks','org', 'admin-c', 'tech-c', 'mnt-by','mnt-lower']});
 is_deeply($clone, { class => 'AsBlock', order => ['as_block', 'descr'], as_block => 'AS30720 - AS30895', descr => ['RIPE NCC ASN block'] }, "Clone object similar with removed attribute");
 
+#
+# default 'append' mode in attribute modification
+#
 $clone->mnt_by({value =>['MNT1-ADD','MNT2-ADD']});
 is_deeply($clone->mnt_by,['MNT1-ADD','MNT2-ADD'],'Array properly added to empty multiple attribute');
 $clone->mnt_by({value =>['MNT3-ADD','MNT4-ADD']});
 is_deeply($clone->mnt_by,['MNT1-ADD','MNT2-ADD','MNT3-ADD','MNT4-ADD'],'Array properly added to multiple attribute');
+
+#
+# 'replace' mode in attribute modification
+#
 $clone->mnt_by({mode => 'replace', value => { old => 'MNT3-ADD', new => 'MNT3-RPL'}});
 is_deeply($clone->mnt_by,['MNT1-ADD','MNT2-ADD','MNT3-RPL','MNT4-ADD'],'Array properly added to multiple attribute');
 eval { $clone->mnt_by({mode => 'unknown', value => { old => 'MNT3-ADD', new => 'MNT3-RPL'}}); };
@@ -62,6 +77,16 @@ like($@ ,qr/new.*replace mode/, "new=>... expected in replace mode");
 eval { $clone->mnt_by({mode => 'replace', value => { new => 'MNT3-ADD'}}); };
 like($@ ,qr/old.*replace mode/, "old=>... expected in replace mode");
 
+#
+# 'delete' mode in attribute modification
+#
+$clone->mnt_by({mode => 'delete', value => { old => 'MNT3-RPL'}});
+is_deeply($clone->mnt_by,['MNT1-ADD','MNT2-ADD','MNT4-ADD'],'Array properly deleted in to multiple attribute');
+eval { $clone->mnt_by({mode => 'delete', value => { new => 'MNT3-ADD'}}); };
+like($@ ,qr/old.*delete mode/, "old=>... expected in delete mode");
+$clone->mnt_by({mode => 'delete', value => { old => '.'}});
+is_deeply($clone->mnt_by,[],'Array properly emptyed through delete wildcard');
+
 my @objects;
 eval { @objects = Net::Whois::Object->query('AS30781', {attribute => 'remarks'}) };