.\" 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::CGI 3pm"
.TH Debbugs::CGI 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::CGI \-\- General routines for the cgi scripts
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Debbugs::CGI qw(:url :html);
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a replacement for parts of common.pl; subroutines in
common.pl will be gradually phased out and replaced with equivalent
(or better) functionality here.
.SH "BUGS"
.IX Header "BUGS"
None known.
.SS "set_url_params"
.IX Subsection "set_url_params"
.Vb 1
\&     set_url_params($uri);
.Ve
.PP
Sets the url params which will be used to generate urls.
.SS "munge_url"
.IX Subsection "munge_url"
.Vb 1
\&     my $url = munge_url($url,%params_to_munge);
.Ve
.PP
Munges a url, replacing parameters with \f(CW%params_to_munge\fR as appropriate.
.SS "version_url"
.IX Subsection "version_url"
.Vb 1
\&     version_url(package => $package,found => $found,fixed => $fixed)
.Ve
.PP
Creates a link to the version cgi script
.IP "package \*(-- source package whose graph to display" 4
.IX Item "package source package whose graph to display"
.PD 0
.IP "found \*(-- arrayref of found versions" 4
.IX Item "found arrayref of found versions"
.IP "fixed \*(-- arrayref of fixed versions" 4
.IX Item "fixed arrayref of fixed versions"
.IP "width \*(-- optional width of graph" 4
.IX Item "width optional width of graph"
.IP "height \*(-- optional height of graph" 4
.IX Item "height optional height of graph"
.IP "info \*(-- display html info surrounding graph; defaults to 1 if width and height are not passed." 4
.IX Item "info display html info surrounding graph; defaults to 1 if width and height are not passed."
.IP "collapse \*(-- whether to collapse the graph; defaults to 1 if width and height are passed." 4
.IX Item "collapse whether to collapse the graph; defaults to 1 if width and height are passed."
.PD
.SS "html_escape"
.IX Subsection "html_escape"
.Vb 1
\&     html_escape($string)
.Ve
.PP
Escapes html entities by calling HTML::Entities::encode_entities;
.SS "cgi_parameters"
.IX Subsection "cgi_parameters"
.Vb 1
\&     cgi_parameters
.Ve
.PP
Returns all of the cgi_parameters from a \s-1CGI\s0 script using CGI::Simple
.SH "HTML"
.IX Header "HTML"
.SS "htmlize_packagelinks"
.IX Subsection "htmlize_packagelinks"
.Vb 1
\&     htmlize_packagelinks
.Ve
.PP
Given a scalar containing a list of packages separated by something
that \*(L"splitpackages\*(R" in Debbugs::CGI can separate, returns a
formatted set of links to packages in html.
.SS "package_links"
.IX Subsection "package_links"
.Vb 1
\&     join(\*(Aq, \*(Aq, package_links(packages => \e@packages))
.Ve
.PP
Given a list of packages, return a list of html which links to the package
.IP "package \*(-- arrayref or scalar of package(s)" 4
.IX Item "package arrayref or scalar of package(s)"
.PD 0
.IP "submitter \*(-- arrayref or scalar of submitter(s)" 4
.IX Item "submitter arrayref or scalar of submitter(s)"
.IP "src \*(-- arrayref or scalar of source(s)" 4
.IX Item "src arrayref or scalar of source(s)"
.IP "maintainer \*(-- arrayref or scalar of maintainer(s)" 4
.IX Item "maintainer arrayref or scalar of maintainer(s)"
.IP "links_only \*(-- return only links, not htmlized links, defaults to returning htmlized links." 4
.IX Item "links_only return only links, not htmlized links, defaults to returning htmlized links."
.IP "class \*(-- class of the a href, defaults to ''" 4
.IX Item "class class of the a href, defaults to ''"
.PD
.SS "bug_links"
.IX Subsection "bug_links"
.Vb 1
\&     join(\*(Aq, \*(Aq, bug_links(bug => \e@packages))
.Ve
.PP
Given a list of bugs, return a list of html which links to the bugs
.IP "bug \*(-- arrayref or scalar of bug(s)" 4
.IX Item "bug arrayref or scalar of bug(s)"
.PD 0
.IP "links_only \*(-- return only links, not htmlized links, defaults to returning htmlized links." 4
.IX Item "links_only return only links, not htmlized links, defaults to returning htmlized links."
.IP "class \*(-- class of the a href, defaults to ''" 4
.IX Item "class class of the a href, defaults to ''"
.PD
.SS "maybelink"
.IX Subsection "maybelink"
.Vb 3
\&     maybelink($in);
\&     maybelink(\*(Aqhttp://foobarbaz,http://bleh\*(Aq,qr/[, ]+/);
\&     maybelink(\*(Aqhttp://foobarbaz,http://bleh\*(Aq,qr/[, ]+/,\*(Aq, \*(Aq);
.Ve
.PP
In the first form, links the link if it looks like a link. In the
second form, first splits based on the regex, then reassembles the
link, linking things that look like links. In the third form, rejoins
the split links with commas and spaces.
.SS "htmlize_addresslinks"
.IX Subsection "htmlize_addresslinks"
.Vb 1
\&     htmlize_addresslinks($prefixfunc,$urlfunc,$addresses,$class);
.Ve
.PP
Generate a comma-separated list of \s-1HTML\s0 links to each address given in
\&\f(CW$addresses\fR, which should be a comma-separated list of \s-1RFC822\s0
addresses. \f(CW$urlfunc\fR should be a reference to a function like mainturl
or submitterurl which returns the \s-1URL\s0 for each individual address.
.SS "bug_linklist"
.IX Subsection "bug_linklist"
.Vb 1
\&     bug_linklist($separator,$class,@bugs)
.Ve
.PP
Creates a set of links to \f(CW@bugs\fR separated by \f(CW$separator\fR with
link class \f(CW$class\fR.
.PP
\&\s-1XXX\s0 Use Params::Validate; we want to be able to support query
arguments here too; we should be able to combine bug_links and this
function into one.
.SH "Forms"
.IX Header "Forms"
.SS "form_options_and_normal_param"
.IX Subsection "form_options_and_normal_param"
.Vb 4
\&     my ($form_option,$param) = form_options_and_normal_param(\e%param)
\&           if $param{form_options};
\&     my $form_option = form_options_and_normal_param(\e%param)
\&           if $param{form_options};
.Ve
.PP
Translates from special form_options to a set of parameters which can
be used to run the current page.
.PP
The idea behind this is to allow complex forms to relatively easily
cause options that the existing cgi scripts understand to be set.
.PP
Currently there are two commands which are understood:
combine, and concatenate.
.PP
\fIcombine\fR
.IX Subsection "combine"
.PP
Combine works by entering key,value pairs into the parameters using
the key field option input field, and the value field option input
field.
.PP
For example, you would have
.PP
.Vb 1
\& <input type="hidden" name="_fo_combine_key_fo_searchkey_value_fo_searchvalue" value="1">
.Ve
.PP
which would combine the _fo_searchkey and _fo_searchvalue input fields, so
.PP
.Vb 2
\& <input type="text" name="_fo_searchkey" value="foo">
\& <input type="text" name="_fo_searchvalue" value="bar">
.Ve
.PP
would yield foo=>'bar' in \f(CW%param\fR.
.PP
\fIconcatenate\fR
.IX Subsection "concatenate"
.PP
Concatenate concatenates values into a single entry in a parameter
.PP
For example, you would have
.PP
.Vb 1
\& <input type="hidden" name="_fo_concatentate_into_foo_with_:_fo_blah_fo_bleargh" value="1">
.Ve
.PP
which would combine the _fo_searchkey and _fo_searchvalue input fields, so
.PP
.Vb 2
\& <input type="text" name="_fo_blah" value="bar">
\& <input type="text" name="_fo_bleargh" value="baz">
.Ve
.PP
would yield foo=>'bar:baz' in \f(CW%param\fR.
.SS "option_form"
.IX Subsection "option_form"
.Vb 4
\&     print option_form(template=>\*(Aqpkgreport_options\*(Aq,
\&                       param   => \e%param,
\&                       form_options => $form_options,
\&                      )
.Ve
.SH "misc"
.IX Header "misc"
.SS "maint_decode"
.IX Subsection "maint_decode"
.Vb 1
\&     maint_decode
.Ve
.PP
Decodes the funky maintainer encoding.
.PP
Don't ask me what in the world it does.
.SH "cache"
.IX Header "cache"
.SS "calculate_etags"
.IX Subsection "calculate_etags"
.Vb 1
\&    calculate_etags(files => [qw(list of files)],additional_data => [qw(any additional data)]);
.Ve
.SS "etag_does_not_match"
.IX Subsection "etag_does_not_match"
.Vb 2
\&     etag_does_not_match(cgi=>$q,files=>[qw(list of files)],
\&         additional_data=>[qw(any additional data)])
.Ve
.PP
Checks to see if the \s-1CGI\s0 request contains an etag which matches the calculated
etag.
.PP
If there wasn't an etag given, or the etag given doesn't match, return the etag.
.PP
If the etag does match, return 0.