* Document english_join

 * Allow setting the english_join options and set reasonable options

diff --git a/Debbugs/Common.pm b/Debbugs/Common.pm
index 87b355924458444536aff9a27c2a1d3a52ee593e..4f85a8f7bb5dadcabb95fe63d8bc7a31d69651c3 100644 (file)
--- a/Debbugs/Common.pm
+++ b/Debbugs/Common.pm
@@ -64,6 +64,8 @@ use Debbugs::MIME qw(decode_rfc1522);
 use Mail::Address;
 use Cwd qw(cwd);
 
+use Params::Validate qw(validate_with :types);
+
 use Fcntl qw(:flock);
 
 our $DEBUG_FH = \*STDERR if not defined $DEBUG_FH;
@@ -506,22 +508,56 @@ sub make_list {
 
 =head2 english_join
 
-     print english_join(', ',' and ',@list);
+     print english_join(list => \@list);
+     print english_join(\@list);
 
 Joins list properly to make an english phrase.
 
+=over
+
+=item normal -- how to separate most values; defaults to ', '
+
+=item last -- how to separate the last two values; defaults to ', and '
+
+=item only_two -- how to separate only two values; defaults to ' and '
+
+=item list -- ARRAYREF values to join; if the first argument is an
+ARRAYREF, it's assumed to be the list of values to join
 
+=back
+
+In cases where C<list> is empty, returns ''; when there is only one
+element, returns that element.
 
 =cut
 
 sub english_join {
-     my ($normal,$last,@list) = @_;
-     if (@list <= 1) {
-         return @list?$list[0]:'';
-     }
-     my $ret = $last . pop(@list);
-     $ret = join($normal,@list) . $ret;
-     return $ret;
+    if (ref $_[0] eq 'ARRAY') {
+       english_join(list=>$_[0]);
+    }
+    my %param = validate_with(param => \@_,
+                             spec  => {normal => {type => SCALAR,
+                                                  default => ', ',
+                                                 },
+                                       last   => {type => SCALAR,
+                                                  default => ', and ',
+                                                 },
+                                       only_two => {type => SCALAR,
+                                                    default => ' and ',
+                                                   },
+                                       list     => {type => ARRAYREF,
+                                                   },
+                                      },
+                            );
+    my @list = @{$param{list}};
+    if (@list <= 1) {
+       return @list?$list[0]:'';
+    }
+    elsif (@list == 2) {
+       return join($param{only_two},@list);
+    }
+    my $ret = $param{last} . pop(@list);
+    return join($param{normal},@list) . $ret;
 }