Document what Debbugs::Status::get_bug_status returns

[debbugs.git] / Debbugs / Status.pm

diff --git a/Debbugs/Status.pm b/Debbugs/Status.pm
index e880783ca87493680b3c751e32cd06df7cf54526..a2aeabef1879cfcaa578fa1c6cc8573d82e868dd 100644 (file)
--- a/Debbugs/Status.pm
+++ b/Debbugs/Status.pm
@@ -108,6 +108,7 @@ our %fields = (originator     => 'submitter',
               blockedby      => 'blocked-by',
              unarchived     => 'unarchived',
              summary        => 'summary',
+             outlook        => 'outlook',
              affects        => 'affects',
              );
 
@@ -217,6 +218,7 @@ sub read_bug{
        }
        return undef;
     }
+    binmode($status_fh,':encoding(UTF-8)');
 
     my %data;
     my @lines;
@@ -239,30 +241,7 @@ sub read_bug{
     }
 
     my %namemap = reverse %fields;
-    for my $field (keys %fields) {
-        $data{$field} = '' unless exists $data{$field};
-    }
-    if ($version < 3) {
-       for my $field (@rfc1522_fields) {
-           $data{$field} = decode_rfc1522($data{$field});
-       }
-    }
     for my $line (@lines) {
-       my @encodings_to_try = qw(utf8 iso8859-1);
-       if ($version >= 3) {
-           @encodings_to_try = qw(utf8);
-       }
-       for (@encodings_to_try) {
-           last if is_utf8($line);
-           my $temp;
-           eval {
-               $temp = decode("$_",$line,Encode::FB_CROAK);
-           };
-           if (not $@) { # only update the line if there are no errors.
-               $line = $temp;
-               last;
-           }
-       }
         if ($line =~ /(\S+?): (.*)/) {
             my ($name, $value) = (lc $1, $2);
            # this is a bit of a hack; we should never, ever have \r
@@ -272,6 +251,14 @@ sub read_bug{
            $data{$namemap{$name}} = $value if exists $namemap{$name};
         }
     }
+    for my $field (keys %fields) {
+       $data{$field} = '' unless exists $data{$field};
+    }
+    if ($version < 3) {
+       for my $field (@rfc1522_fields) {
+           $data{$field} = decode_rfc1522($data{$field});
+       }
+    }
     $data{severity} = $config{default_severity} if $data{severity} eq '';
     for my $field (qw(found_versions fixed_versions found_date fixed_date)) {
         $data{$field} = [split ' ', $data{$field}];
@@ -1121,6 +1108,63 @@ a source package). Defaults to true.
 Note: Currently the version information is cached; this needs to be
 changed before using this function in long lived programs.
 
+=head3 Returns
+
+Currently returns a hashref of status with the following keys.
+
+=over
+
+=item id -- bug number
+
+=item bug_num -- duplicate of id
+
+=item keywords -- tags set on the bug, including usertags if bugusertags passed.
+
+=item tags -- duplicate of keywords
+
+=item package -- name of package that the bug is assigned to
+
+=item severity -- severity of the bug
+
+=item pending -- pending state of the bug; one of following possible
+values; values listed later have precedence if multiple conditions are
+satisifed:
+
+=over
+
+=item pending -- default state
+
+=item forwarded -- bug has been forwarded
+
+=item pending-fixed -- bug is tagged pending
+
+=item fixed -- bug is tagged fixed
+
+=item absent -- bug does not apply to this distribution/architecture
+
+=item done -- bug is resolved in this distribution/architecture
+
+=back
+
+=item location -- db-h or archive; the location in the filesystem
+
+=item subject -- title of the bug
+
+=item last_modified -- epoch that the bug was last modified
+
+=item date -- epoch that the bug was filed
+
+=item originator -- bug reporter
+
+=item log_modified -- epoch that the log file was last modified
+
+=item msgid -- Message id of the original bug report
+
+=back
+
+
+Other key/value pairs are returned but are not currently documented here.
+
 =cut
 
 sub get_bug_status {