.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Debbugs::Bugs 3pm"
.TH Debbugs::Bugs 3pm "2018-02-26" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Debbugs::Bugs \-\- Bug selection routines for debbugs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Debbugs::Bugs qw(get_bugs);
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a replacement for all of the various methods of
selecting different types of bugs.
.PP
It implements a single function, get_bugs, which defines the master
interface for selecting bugs.
.PP
It attempts to use subsidiary functions to actually do the selection,
in the order specified in the configuration files. [Unless you're
insane, they should be in order from fastest (and often most
incomplete) to slowest (and most complete).]
.SH "BUGS"
.IX Header "BUGS"
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "get_bugs"
.IX Subsection "get_bugs"
.Vb 1
\&     get_bugs()
.Ve
.PP
\fIParameters\fR
.IX Subsection "Parameters"
.PP
The following parameters can either be a single scalar or a reference
to an array. The parameters are ANDed together, and the elements of
arrayrefs are a parameter are ORed. Future versions of this may allow
for limited regular expressions, and/or more complex expressions.
.IP "package \*(-- name of the binary package" 4
.IX Item "package name of the binary package"
.PD 0
.IP "src \*(-- name of the source package" 4
.IX Item "src name of the source package"
.IP "maint \*(-- address of the maintainer" 4
.IX Item "maint address of the maintainer"
.IP "submitter \*(-- address of the submitter" 4
.IX Item "submitter address of the submitter"
.IP "severity \*(-- severity of the bug" 4
.IX Item "severity severity of the bug"
.IP "status \*(-- status of the bug" 4
.IX Item "status status of the bug"
.IP "tag \*(-- bug tags" 4
.IX Item "tag bug tags"
.IP "owner \*(-- owner of the bug" 4
.IX Item "owner owner of the bug"
.IP "correspondent \*(-- address of someone who sent mail to the log" 4
.IX Item "correspondent address of someone who sent mail to the log"
.IP "affects \*(-- bugs which affect this package" 4
.IX Item "affects bugs which affect this package"
.IP "dist \*(-- distribution (I don't know about this one yet)" 4
.IX Item "dist distribution (I don't know about this one yet)"
.IP "bugs \*(-- list of bugs to search within" 4
.IX Item "bugs list of bugs to search within"
.IP "function \*(-- see description below" 4
.IX Item "function see description below"
.PD
.PP
\fISpecial options\fR
.IX Subsection "Special options"
.PP
The following options are special options used to modulate how the
searches are performed.
.IP "archive \*(-- whether to search archived bugs or normal bugs; defaults to false. As a special case, if archive is 'both', but archived and unarchived bugs are returned." 4
.IX Item "archive whether to search archived bugs or normal bugs; defaults to false. As a special case, if archive is 'both', but archived and unarchived bugs are returned."
.PD 0
.IP "usertags \*(-- set of usertags and the bugs they are applied to" 4
.IX Item "usertags set of usertags and the bugs they are applied to"
.PD
.PP
\fISubsidiary routines\fR
.IX Subsection "Subsidiary routines"
.PP
All subsidiary routines get passed exactly the same set of options as
get_bugs. If for some reason they are unable to handle the options
passed (for example, they don't have the right type of index for the
type of selection) they should die as early as possible. [Using
Params::Validate and/or die when files don't exist makes this fairly
trivial.]
.PP
This function will then immediately move on to the next subroutine,
giving it the same arguments.
.PP
\fIfunction\fR
.IX Subsection "function"
.PP
This option allows you to provide an arbitrary function which will be
given the information in the index.db file. This will be super, super
slow, so only do this if there's no other way to write the search.
.PP
You'll be given a list (which you can turn into a hash) like the
following:
.PP
.Vb 7
\& (pkg => [\*(Aqa\*(Aq,\*(Aqb\*(Aq], # may be a scalar (most common)
\&  bug => 1234,
\&  status => \*(Aqpending\*(Aq,
\&  submitter => \*(Aqboo@baz.com\*(Aq,
\&  severity => \*(Aqserious\*(Aq,
\&  tags => [\*(Aqa\*(Aq,\*(Aqb\*(Aq,\*(Aqc\*(Aq], # may be an empty arrayref
\& )
.Ve
.PP
The function should return 1 if the bug should be included; 0 if the
bug should not.
.SS "count_bugs"
.IX Subsection "count_bugs"
.Vb 1
\&     count_bugs(function => sub {...})
.Ve
.PP
Uses a subroutine to classify bugs into categories and return the
number of bugs which fall into those categories
.SS "newest_bug"
.IX Subsection "newest_bug"
.Vb 1
\&     my $bug = newest_bug();
.Ve
.PP
Returns the bug number of the newest bug, which is nextnumber\-1.
.SS "bug_filter"
.IX Subsection "bug_filter"
.Vb 1
\&     bug_filter
.Ve
.PP
Allows filtering bugs on commonly used criteria
.SS "get_bugs_by_idx"
.IX Subsection "get_bugs_by_idx"
This routine uses the by\-$index.idx indicies to try to speed up
searches.
.SS "get_bugs_flatfile"
.IX Subsection "get_bugs_flatfile"
This is the fallback search routine. It should be able to complete all
searches. [Or at least, that's the idea.]
.SH "PRIVATE FUNCTIONS"
.IX Header "PRIVATE FUNCTIONS"
.SS "_\|_handle_pkg_src_and_maint"
.IX Subsection "__handle_pkg_src_and_maint"
.Vb 3
\&     my @packages = _\|_handle_pkg_src_and_maint(map {exists $param{$_}?($_,$param{$_}):()}
\&                                               qw(package src maint)
\&                                              );
.Ve
.PP
Turn package/src/maint into a list of packages