Debbugs::CGI(3pm)

🎀 NAME 🎀

Debbugs::CGI — bestie, this is the module with all the general routines for the cgi scripts. That's the whole job description. It's the grab-bag of URL munging, HTML escaping, link building and caching helpers that the debbugs CGIs lean on. 💅

✨ SYNOPSIS ✨

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

That's it, that's the whole vibe check. Import it and go. 🦋

💖 DESCRIPTION 💖

Okay so real talk: this module is a replacement for parts of common.pl. The subroutines hanging out in common.pl are getting gradually phased out and replaced with equivalent (or better, fr fr better) functionality in here instead. So if you're still calling the old stuff, it's giving "living in the past" energy. 🙈

💀 BUGS 💀

None known. Not a single one. Zero. Iconic behaviour honestly. ✨

🌸 set_url_params 🌸

set_url_params($uri);

Sets the url params which will be used to generate urls. That's the whole bit — you hand it a $uri and it sets the params. Slay.

🦋 munge_url 🦋

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

Munges a url, replacing parameters with %params_to_munge as appropriate. Yes, "munges" is the technical term, no I will not elaborate, it's literally in the function name. 💅

👑 version_url 👑

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

Creates a link to the version cgi script. The args, in the order the original lists them:

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

lowkey obsessed with the way info and collapse flip-flop depending on whether you passed width and height. keep that in mind bestie, it's the whole trick. 🫶

🎀 html_escape 🎀

html_escape($string)

Escapes html entities by calling HTML::Entities::encode_entities; . It does exactly one thing and it does it through somebody else's function, which is honestly main character delegation energy. ✨

🍓 cgi_parameters 🍓

cgi_parameters

Returns all of the cgi_parameters from a CGI script using CGI::Simple. No arguments, it just goes and gets them. 🤝

🌈 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. So like, it takes your gross string of packages and turns it into a cute little link set. ate. 💜

💅 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 ''

note that class defaults to the empty string, not to something spicy. keep it real. 🌸

🦋 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 ''

(yeah, the synopsis calls the arg bug but passes \@packages, that's just how the original rolls, don't @ me 😭)

💖 maybelink 💖

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

Three forms, three moods:

1. In the first form, links the link if it looks like a link.
2. In the second form, first splits based on the regex, then reassembles the link, linking things that look like links.
3. In the third form, rejoins the split links with commas and spaces.

So it's a "maybe I'll link it, maybe I won't" situation. It's giving unbothered. 😌

🌸 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. Yeah bestie, you gotta hand it a function, it's not gonna guess. 💅

✨ 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. — that's straight from the page, it's a todo note, not a done thing. Do not @ me about it. 💀

🎀 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. Which honestly? Big brain. 🧠✨

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.

⚠️ not me pointing out that the hidden input above says concatentate and the prose says _fo_searchkey/_fo_searchvalue while the actual inputs are _fo_blah/_fo_bleargh — that is exactly what the page says, character for character, so I'm leaving it. If you're copy-pasting names outta here, copy them exactly. 🙈

🍓 option_form 🍓

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

That's the whole documented signature. Print it, ship it. 🫶

💅 misc 💅

👑 maint_decode 👑

maint_decode

Decodes the funky maintainer encoding.

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

…and that is literally what the manual page says, bestie, I am not adding a single thing. Nobody knows. It decodes the funky encoding. It's a mystery wrapped in a subroutine. 💀✨

⭐ cache ⭐

🎀 calculate_etags 🎀

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

That's the signature, one line, go wild. 🌸

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

okay so lowkey read that name carefully: it returns the etag when they don't match, and 0 when they do match. That's the entire contract, don't get it twisted. 🔥

---

and that's the whole page, bestie 💖 this was Debbugs::CGI(3pm) from the User Contributed Perl Documentation, and this version is perl v5.40.1, dated 2026-04-27. no cap, every flag, arg, default and code block survived the glow-up. go forth and CGI 🦋✨💅