clarify documentation for select() #77

This also modernises the test slightly.

Author: simbabque

Changes

@@ -8,6 +8,7 @@ Revision history for WWW::Mechanize
     - Raise minimum Perl to 5.8 to match what we test, what dependencies
       depend on, etc. (GH#352) (James Raspass)
     [DOCUMENTATION]
+    - Clarify documentation for select() (GH#77) (Julien Fiegehenn)
     - Various POD fixes (Julien Fiegehenn)
     [TESTS]
     - Test that follow_link(n=> 'all') warns (Kueppo Tcheukam)

lib/WWW/Mechanize.pm

@@ -1977,23 +1977,61 @@ sub field {
     }
 }
 
-=head2 $mech->select($name, $value)
+=head2 $mech->select($name, $new_or_additional_single_value)
 
-=head2 $mech->select($name, \@values)
+=head2 $mech->select($name, \%new_single_value_by_number)
+
+=head2 $mech->select($name, \@new_list_of_values)
+
+=head2 $mech->select($name, \%new_list_of_values_by_number)
 
 Given the name of a C<select> field, set its value to the value
-specified.  If the field is not C<< <select multiple> >> and the
-C<$value> is an array, only the B<first> value will be set.  [Note:
-the documentation previously claimed that only the last value would
-be set, but this was incorrect.]  Passing C<$value> as a hash with
-an C<n> key selects an item by number (e.g.
-C<< {n => 3} >> or C<< {n => [2,4]} >>).
+specified.
+
+    # select 'foo'
+    $mech->select($name, 'foo');
+
+If the field is not C<< <select multiple> >> and the
+C<$value> is an array reference, only the B<first> value will be set.  [Note:
+until version 1.05_03 the documentation claimed that only the last value would
+be set, but this was incorrect.]
+
+    # select 'bar'
+    $mech->select($name, ['bar', 'ignored', 'ignored']);
+
+Passing C<$value> as a hash reference with an C<n> key selects an item by number.
+
+    # select the third value
+    $mech->select($name, {n => 3});
+
 The numbering starts at 1.  This applies to the current form.
 
 If you have a field with C<< <select multiple> >> and you pass a single
 C<$value>, then C<$value> will be added to the list of fields selected,
-without clearing the others.  However, if you pass an array reference,
-then all previously selected values will be cleared.
+without clearing the others.
+
+    # add 'bar' to the list of selected values
+    $mech->select($name, 'bar');
+
+However, if you pass an array reference, then all previously selected values
+will be cleared and replaced with all values inside the array reference.
+
+    # replace the selection with 'foo' and 'bar'
+    $mech->select($name, ['foo', 'bar']);
+
+This also works when selecting by numbers, in which case the value of the C<n>
+key will be an array reference of value numbers you want to replace the
+selection with.
+
+    # replace the selection with the 2nd and 4th element
+    $mech->select($name, {n => [2, 4]});
+
+To add multiple additional values to the list of selected fields without
+clearing, call C<select> in the simple C<$value> form with each single value
+in a loop.
+
+    # add all values in the array to the selection
+    $mech->select($name, $_) for @additional_values;
 
 Returns true on successfully setting the value. On failure, returns
 false and calls C<< $self->warn() >> with an error message.

t/select.t

@@ -2,7 +2,8 @@
 
 use warnings;
 use strict;
-use Test::More tests => 14;
+use Test::More;
+use Test::Warn qw( warning_like );
 use URI::file ();
 
 BEGIN {
@@ -32,19 +33,23 @@ $form = $mech->current_form();
 # Multi-select
 
 # pass multiple values to a multi select
+$form->param('multilist', undef);
 $mech->select('multilist', \@sendmulti);
 @return = $form->param('multilist');
 is_deeply(\@return, \@sendmulti, 'multi->multi value is ' . join(' ', @return));
 
+$form->param('multilist', undef);
 $mech->select('multilist', \%sendmulti);
 @return = $form->param('multilist');
 is_deeply(\@return, \@sendmulti, 'multi->multi value is ' . join(' ', @return));
 
 # pass a single value to a multi select
+$form->param('multilist', undef);
 $mech->select('multilist', $sendsingle);
 $return = $form->param('multilist');
 is($return, $sendsingle, "single->multi value is '$return'");
 
+$form->param('multilist', undef);
 $mech->select('multilist', \%sendsingle);
 $return = $form->param('multilist');
 is($return, $sendsingle, "single->multi value is '$return'");
@@ -53,29 +58,33 @@ is($return, $sendsingle, "single->multi value is '$return'");
 # Single select
 
 # pass multiple values to a single select (only the _first_ should be set)
+$form->param('singlelist', undef);
 $mech->select('singlelist', \@sendmulti);
 @return = $form->param('singlelist');
 is_deeply(\@return, \@singlereturn, 'multi->single value is ' . join(' ', @return));
 
+$form->param('singlelist', undef);
 $mech->select('singlelist', \%sendmulti);
 @return = $form->param('singlelist');
 is_deeply(\@return, \@singlereturn, 'multi->single value is ' . join(' ', @return));
 
 
 # pass a single value to a single select
+$form->param('singlelist', undef);
 $rv = $mech->select('singlelist', $sendsingle);
 $return = $form->param('singlelist');
 is($return, $sendsingle, "single->single value is '$return'");
 
+$form->param('singlelist', undef);
 $rv = $mech->select('singlelist', \%sendsingle);
 $return = $form->param('singlelist');
 is($return, $sendsingle, "single->single value is '$return'");
 
 # test return value from $mech->select
 is($rv, 1, 'return 1 after successful select');
 
-EAT_THE_WARNING: { # Mech complains about the non-existent field
-    local $SIG{__WARN__} = sub {};
-    $rv = $mech->select('missing_list', 1);
-}
-is($rv, undef, 'return undef after failed select');
+warning_like { $rv = $mech->select( 'missing_list', 1 ) } qr/not found/,
+    'warning when field is not found';
+is( $rv, undef, 'return undef after failed select' );
+
+done_testing;