Debbugs::Status -- Routines for dealing with summary and status files
use Debbugs::Status;
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
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(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.
unfilelock(); if something not undef is returned from read_bug.One of bug or summary must be passed. This function will return undef on failure, and will die if improper arguments are passed.
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.
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($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
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.
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.
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.
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($bug_num,$status,$location,$minversion,$disablebughook)
Writes the bug status and summary files out.
Skips writting out a status file if minversion is 2
Does not call bughook if disablebughook is true.
unlockwritebug($bug_num,$status,$location,$minversion,$disablebughook);
Writes a bug, then calls unfilelock; see writebug for what these options mean.
The following functions are exported with the :versions tag
addfoundversions($status,$package,$version,$isbinary);
All use of this should be phased out in favor of Debbugs::Control::fixed/found
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 compatibilty.
splitpackages($pkgs)
Split a package string from the status file into a list of package names.
bug_archiveable(bug => $bug_num);
Options
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.
my $status = get_bug_status(bug => $nnn);
my $status = get_bug_status($bug_num)
Note: Currently the version information is cached; this needs to be changed before using this function in long lived programs.
Currently returns a hashref of status with the following keys.
Other key/value pairs are returned but are not currently documented here.
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.
max_buggy()
Note: Currently the version information is cached; this needs to be changed before using this function in long lived programs.
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.]