From: Don Armstrong <don@donarmstrong.com>
Date: Wed, 31 Dec 2008 18:59:15 +0000 (+0100)
Subject:  * Document english_join
X-Git-Tag: release/2.6.0~461^2~76
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=7da201765899adae872b4ff869d292f230fb7112;p=debbugs.git

 * Document english_join
 * Allow setting the english_join options and set reasonable options
---

diff --git a/Debbugs/Common.pm b/Debbugs/Common.pm
index 87b3559..4f85a8f 100644
--- 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;
 }