NAME

       Debbugs::Status -- Routines for dealing with summary and status files

SYNOPSIS

       use Debbugs::Status;

DESCRIPTION

       This module is a replacement for the parts of errorlib.pl which write and read status and
       summary files.

       It also contains generic routines for returning information about the status of a
       particular bug

FUNCTIONS

   readbug
            readbug($bug_num,$location)
            readbug($bug_num)

       Reads a summary file from the archive given a bug number and a bug location. Valid
       locations are those understood by "getbugcomponent"

   read_bug
            read_bug(bug => $bug_num,
                     location => 'archive',
                    );
            read_bug(summary => 'path/to/bugnum.summary');
            read_bug($bug_num);

       A more complete function than readbug; it enables you to pass a full path to the summary
       file instead of the bug number and/or location.

       Options

       bug -- the bug number
       location -- optional location which is passed to getbugcomponent
       summary -- complete path to the .summary file which will be read
       lock -- whether to obtain a lock for the bug to prevent something modifying it while the
       bug has been read. You must call "unfilelock();" if something not undef is returned from
       read_bug.
       locks -- hashref of already obtained locks; incremented as new locks are needed, and
       decremented as locks are released on particular files.

       One of "bug" or "summary" must be passed. This function will return undef on failure, and
       will die if improper arguments are passed.

   split_status_fields
            my @data = split_status_fields(@data);

       Splits splittable status fields (like package, tags, blocks, blockedby, etc.) into
       arrayrefs (use make_list on these). Keeps the passed @data intact using dclone.

       In scalar context, returns only the first element of @data.

   join_status_fields
            my @data = join_status_fields(@data);

       Handles joining the splitable status fields. (Basically, the inverse of
       split_status_fields.

       Primarily called from makestatus, but may be useful for other functions after calling
       split_status_fields (or for legacy functions if we transition to split fields by default).

   lockreadbug
            lockreadbug($bug_num,$location)

       Performs a filelock, then reads the bug; the bug is unlocked if the return is undefined,
       otherwise, you need to call unfilelock or unlockwritebug.

       See readbug above for information on what this returns

   lockreadbugmerge
            my ($locks, $data) = lockreadbugmerge($bug_num,$location);

       Performs a filelock, then reads the bug. If the bug is merged, locks the merge lock.
       Returns a list of the number of locks and the bug data.

   lock_read_all_merged_bugs
            my ($locks,@bug_data) = lock_read_all_merged_bugs($bug_num,$location);

       Performs a filelock, then reads the bug passed. If the bug is merged, locks the merge
       lock, then reads and locks all of the other merged bugs. Returns a list of the number of
       locks and the bug data for all of the merged bugs.

       Will also return undef if any of the merged bugs failed to be read, even if all of the
       others were read properly.

   new_bug
               my $new_bug_num = new_bug(copy => $data->{bug_num});

       Creates a new bug and returns the new bug number upon success.

       Dies upon failures.

   makestatus
            my $content = makestatus($status,$version)
            my $content = makestatus($status);

       Creates the content for a status file based on the $status hashref passed.

       Really only useful for writebug

       Currently defaults to version 2 (non-encoded rfc1522 names) but will eventually default to
       version 3. If you care, you should specify a version.

   writebug
            writebug($bug_num,$status,$location,$minversion,$disablebughook)

       Writes the bug status and summary files out.

       Skips writing out a status file if minversion is 2

       Does not call bughook if disablebughook is true.

   unlockwritebug
            unlockwritebug($bug_num,$status,$location,$minversion,$disablebughook);

       Writes a bug, then calls unfilelock; see writebug for what these options mean.

VERSIONS

       The following functions are exported with the :versions tag

   addfoundversions
            addfoundversions($status,$package,$version,$isbinary);

       All use of this should be phased out in favor of Debbugs::Control::fixed/found

   removefoundversions
            removefoundversions($data,$package,$versiontoremove)

       Removes found versions from $data

       If a version is fully qualified (contains /) only versions matching exactly are removed.
       Otherwise, all versions matching the version number are removed.

       Currently $package and $isbinary are entirely ignored, but accepted for backwards
       compatibility.

   splitpackages
            splitpackages($pkgs)

       Split a package string from the status file into a list of package names.

   bug_archiveable
            bug_archiveable(bug => $bug_num);

       Options

       bug -- bug number (required)
       status -- Status hashref returned by read_bug or get_bug_status (optional)
       version -- Debbugs::Version information (optional)
       days_until -- return days until the bug can be archived

       Returns 1 if the bug can be archived Returns 0 if the bug cannot be archived

       If days_until is true, returns the number of days until the bug can be archived, -1 if it
       cannot be archived. 0 means that the bug can be archived the next time the archiver runs.

       Returns undef on failure.

   get_bug_status
            my $status = get_bug_status(bug => $nnn);

            my $status = get_bug_status($bug_num)

       Options

       bug -- scalar bug number
       status -- optional hashref of bug status as returned by readbug (can be passed to avoid
       rereading the bug information)
       bug_index -- optional tied index of bug status infomration; currently not correctly
       implemented.
       version -- optional version(s) to check package status at
       dist -- optional distribution(s) to check package status at
       arch -- optional architecture(s) to check package status at
       bugusertags -- optional hashref of bugusertags
       sourceversion -- optional arrayref of source/version; overrides dist, arch, and version.
       [The entries in this array must be in the "source/version" format.] Eventually this can be
       used to for caching.
       indicatesource -- if true, indicate which source packages this bug could belong to (or
       does belong to in the case of bugs assigned to 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.

       Returns

       Currently returns a hashref of status with the following keys.

       id -- bug number
       bug_num -- duplicate of id
       keywords -- tags set on the bug, including usertags if bugusertags passed.
       tags -- duplicate of keywords
       package -- name of package that the bug is assigned to
       severity -- severity of the bug
       pending -- pending state of the bug; one of following possible values; values listed later
       have precedence if multiple conditions are satisifed:
           pending -- default state
           forwarded -- bug has been forwarded
           pending-fixed -- bug is tagged pending
           fixed -- bug is tagged fixed
           absent -- bug does not apply to this distribution/architecture
           done -- bug is resolved in this distribution/architecture
       location -- db-h or archive; the location in the filesystem
       subject -- title of the bug
       last_modified -- epoch that the bug was last modified
       date -- epoch that the bug was filed
       originator -- bug reporter
       log_modified -- epoch that the log file was last modified
       msgid -- Message id of the original bug report

       Other key/value pairs are returned but are not currently documented here.

   bug_presence
            my $precence = bug_presence(bug => nnn,
                                        ...
                                       );

       Returns 'found', 'absent', 'fixed' or undef based on whether the bug is found, absent,
       fixed, or no information is available in the distribution (dist) and/or architecture
       (arch) specified.

       Options

       bug -- scalar bug number
       status -- optional hashref of bug status as returned by readbug (can be passed to avoid
       rereading the bug information)
       bug_index -- optional tied index of bug status infomration; currently not correctly
       implemented.
       version -- optional version to check package status at
       dist -- optional distribution to check package status at
       arch -- optional architecture to check package status at
       sourceversion -- optional arrayref of source/version; overrides dist, arch, and version.
       [The entries in this array must be in the "source/version" format.] Eventually this can be
       used to for caching.

   max_buggy
            max_buggy()

       Options

       bug -- scalar bug number
       sourceversion -- optional arrayref of source/version; overrides dist, arch, and version.
       [The entries in this array must be in the "source/version" format.] Eventually this can be
       used to for caching.

       Note: Currently the version information is cached; this needs to be changed before using
       this function in long lived programs.

   buggy
            buggy(bug => nnn,
                  found => \@found,
                  fixed => \@fixed,
                  package => 'foo',
                  version => '1.0',
                 );

       Returns the output of Debbugs::Versions::buggy for a particular package, version and
       found/fixed set. Automatically turns found, fixed and version into source/version strings.

       Caching can be had by using the version_cache, but no attempt to check to see if the on
       disk information is more recent than the cache is made. [This will need to be fixed for
       long-lived processes.]

indexdb

   generate_index_db_line
               my $data = read_bug(bug => $bug,
                                   location => $initialdir);
               # generate_index_db_line hasn't been written yet at all.
               my $line = generate_index_db_line($data);

       Returns a line for a bug suitable to be written out to index.db.

PRIVATE FUNCTIONS