Debbugs::CGI(3pm)

NAME
Debbugs::CGI -- General routines for the cgi scripts

SYNOPSIS
use Debbugs::CGI qw(:url :html);

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.

BUGS
None known.

  set_url_params
     set_url_params($uri);

Sets the url params which will be used to generate urls.

  munge_url
     my $url = munge_url($url,%params_to_munge);

Munges a url, replacing parameters with %params_to_munge as appropriate.

  version_url
     version_url(package => $package,found => $found,fixed => $fixed)

Creates a link to the version cgi script

package -- source package whose graph to display
found -- arrayref of found versions
fixed -- arrayref of fixed versions
width -- optional width of graph
height -- optional height of graph
info -- display html info surrounding graph; defaults to 1 if width and height are not passed.
collapse -- whether to collapse the graph; defaults to 1 if width and height are passed.

  html_escape
     html_escape($string)

Escapes html entities by calling HTML::Entities::encode_entities;

  cgi_parameters
     cgi_parameters

Returns all of the cgi_parameters from a CGI script using CGI::Simple

HTML

  htmlize_packagelinks
     htmlize_packagelinks

Given a scalar containing a list of packages separated by something that "splitpackages" in Debbugs::CGI can separate, returns a formatted set of links to packages in html.

  package_links
     join(', ', package_links(packages => \@packages))

Given a list of packages, return a list of html which links to the package

package -- arrayref or scalar of package(s)
submitter -- arrayref or scalar of submitter(s)
src -- arrayref or scalar of source(s)
maintainer -- arrayref or scalar of maintainer(s)
links_only -- return only links, not htmlized links, defaults to returning htmlized links.
class -- class of the a href, defaults to ''

  bug_links
     join(', ', bug_links(bug => \@packages))

Given a list of bugs, return a list of html which links to the bugs

bug -- arrayref or scalar of bug(s)
links_only -- return only links, not htmlized links, defaults to returning htmlized links.
class -- class of the a href, defaults to ''

  maybelink
     maybelink($in);
     maybelink('http://foobarbaz,http://bleh',qr/[, ]+/);
     maybelink('http://foobarbaz,http://bleh',qr/[, ]+/,', ');

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.

  htmlize_addresslinks
     htmlize_addresslinks($prefixfunc,$urlfunc,$addresses,$class);

Generate a comma-separated list of HTML links to each address given in $addresses, which should be a comma-separated list of RFC822 addresses. $urlfunc should be a reference to a function like mainturl or submitterurl which returns the URL for each individual address.

  bug_linklist
     bug_linklist($separator,$class,@bugs)

Creates a set of links to @bugs separated by $separator with link class $class.

XXX 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.

Forms

  form_options_and_normal_param
     my ($form_option,$param) = form_options_and_normal_param(\%param)
           if $param{form_options};
     my $form_option = form_options_and_normal_param(\%param)
           if $param{form_options};

Translates from special form_options to a set of parameters which can be used to run the current page.

The idea behind this is to allow complex forms to relatively easily cause options that the existing cgi scripts understand to be set.

Currently there are two commands which are understood: combine, and concatenate.

combine

Combine works by entering key,value pairs into the parameters using the key field option input field, and the value field option input field.

For example, you would have

 <input type="hidden" name="_fo_combine_key_fo_searchkey_value_fo_searchvalue" value="1">

which would combine the _fo_searchkey and _fo_searchvalue input fields, so

 <input type="text" name="_fo_searchkey" value="foo">
 <input type="text" name="_fo_searchvalue" value="bar">

would yield foo=>'bar' in %param.

concatenate

Concatenate concatenates values into a single entry in a parameter

For example, you would have

 <input type="hidden" name="_fo_concatentate_into_foo_with_:_fo_blah_fo_bleargh" value="1">

which would combine the _fo_searchkey and _fo_searchvalue input fields, so

 <input type="text" name="_fo_blah" value="bar">
 <input type="text" name="_fo_bleargh" value="baz">

would yield foo=>'bar:baz' in %param.

  option_form
     print option_form(template=>'pkgreport_options',
                       param   => \%param,
                       form_options => $form_options,
                      )

misc

  maint_decode
     maint_decode

Decodes the funky maintainer encoding.

Don't ask me what in the world it does.

cache

  calculate_etags
    calculate_etags(files => [qw(list of files)],additional_data => [qw(any additional data)]);

  etag_does_not_match
     etag_does_not_match(cgi=>$q,files=>[qw(list of files)],
         additional_data=>[qw(any additional data)])

Checks to see if the CGI request contains an etag which matches the calculated etag.

If there wasn't an etag given, or the etag given doesn't match, return the etag.

If the etag does match, return 0.