* Document english_join

[debbugs.git] / Debbugs / Common.pm

diff --git a/Debbugs/Common.pm b/Debbugs/Common.pm
index a4d7cf109136c99f370b40fd9b3b1515e38c02c4..4f85a8f7bb5dadcabb95fe63d8bc7a31d69651c3 100644 (file)
--- a/Debbugs/Common.pm
+++ b/Debbugs/Common.pm
@@ -43,7 +43,7 @@ BEGIN{
                                qw(getmaintainers_reverse),
                                qw(getpseudodesc),
                               ],
-                    misc   => [qw(make_list globify_scalar english_join)],
+                    misc   => [qw(make_list globify_scalar english_join checkpid)],
                     date   => [qw(secs_to_english)],
                     quit   => [qw(quit)],
                     lock   => [qw(filelock unfilelock lockpid)],
@@ -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;
@@ -162,6 +164,8 @@ sub get_hashname {
 
 Returns the path to the logfile corresponding to the bug.
 
+Returns undef if the bug does not exist.
+
 =cut
 
 sub buglog {
@@ -169,7 +173,8 @@ sub buglog {
     my $location = getbuglocation($bugnum, 'log');
     return getbugcomponent($bugnum, 'log', $location) if ($location);
     $location = getbuglocation($bugnum, 'log.gz');
-    return getbugcomponent($bugnum, 'log.gz', $location);
+    return getbugcomponent($bugnum, 'log.gz', $location) if ($location);
+    return undef;
 }
 
 
@@ -417,15 +422,9 @@ Returns 1 on success, false on failure; dies on unusual errors.
 sub lockpid {
      my ($pidfile) = @_;
      if (-e $pidfile) {
-         my $pidfh = IO::File->new($pidfile, 'r') or
-              die "Unable to open pidfile $pidfile: $!";
-         local $/;
-         my $pid = <$pidfh>;
-         ($pid) = $pid =~ /(\d+)/;
-         if (defined $pid and kill(0,$pid)) {
-              return 0;
-         }
-         close $pidfh;
+         my $pid = checkpid($pidfile);
+         die "Unable to read pidfile $pidfile: $!" if not defined $pid;
+         return 0 if $pid != 0;
          unlink $pidfile or
               die "Unable to unlink stale pidfile $pidfile $!";
      }
@@ -436,6 +435,35 @@ sub lockpid {
      return 1;
 }
 
+=head2 checkpid
+
+     checkpid('/path/to/pidfile');
+
+Checks a pid file and determines if the process listed in the pidfile
+is still running. Returns the pid if it is, 0 if it isn't running, and
+undef if the pidfile doesn't exist or cannot be read.
+
+=cut
+
+sub checkpid{
+     my ($pidfile) = @_;
+     if (-e $pidfile) {
+         my $pidfh = IO::File->new($pidfile, 'r') or
+              return undef;
+         local $/;
+         my $pid = <$pidfh>;
+         close $pidfh;
+         ($pid) = $pid =~ /(\d+)/;
+         if (defined $pid and kill(0,$pid)) {
+              return $pid;
+         }
+         return 0;
+     }
+     else {
+         return undef;
+     }
+}
+
 
 =head1 QUIT
 
@@ -480,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;
 }