Form(3)

📦

version 0.952 · 2 versions

0.952 · fedora 43 (latest)
0.952 · fedora 44

💖 Form(3) — HTTP::Request::Form 💖

okay bestie, gather round, because this one is from the User Contributed Perl Documentation collection and it is so useful if you've ever wanted your Perl code to just... fill out a web form for you. no cap.

✨ NAME ✨

HTTP::Request::Form — construct HTTP::Request objects for form processing. it's giving automated form-filling main character energy 🫶

🌸 SYNOPSIS 🌸

okay so imagine you wanna query Altavista for "perl" straight from the commandline. this is the vibe:

use URI::URL;
use LWP::UserAgent;
use HTTP::Request;
use HTTP::Request::Common;
use HTTP::Request::Form;
use HTML::TreeBuilder 3.0;

my $ua = LWP::UserAgent->new;
my $url = url 'http://www.altavista.digital.com/';
my $res = $ua->request(GET $url);
my $tree = HTML::TreeBuilder->new;
$tree->parse($res->content);
$tree->eof();

my @forms = $tree->find_by_tag_name('FORM');
die "What, no forms in $url?" unless @forms;
my $f = HTTP::Request::Form->new($forms[0], $url);
$f->field("q", "perl");
my $response = $ua->request($f->press("search"));
print $response->content if $response->is_success;

literally the whole pipeline: fetch the page, parse it, find the form, fill it in, press the button, print the tea. 💅

🦋 DESCRIPTION 🦋

so this module is an extension of the HTTP::Request suite. what it does is make processing forms in a user agent easy — you can fill out fields, query fields, selections and buttons, and press buttons. that's the whole vibe.

it works off parse trees of documents generated by HTML::TreeBuilder (especially the forms parts you get extracted with extract_links), and then it builds its own internal representation of forms, and from that it generates the request objects used to process the form application. iconic honestly. ✨

👑 CLASS METHODS 👑

new($form [, $base [, $debug]]) — the new-method constructs a brand new form processor, bestie. it takes an HTML::Element object containing a FORM element or an ISINDEX element as its single parameter. if a base-url gets passed in as an extra parameter, that's what's used to make the form-url absolute relative to the given URL. and if debugging is true, the functions below get a little bit "talky" on stdio. 🙈
new_many($tree_part [, $base [, $debug]]) — this one returns a list of freshly constructed form processors. it's basically new but it can apply to any part of an HTML::Element tree, root included — it builds a new form processor for every FORM element at or under $tree_part.

heads up: that return list might have zero, one or many new objects in it, depending on how many FORM (or ISINDEX) elements turned up. no promises.

also — form elements (like INPUT, etc.) that show up outside of FORM elements get counted as part of the preceding FORM element. (and if there's no preceding FORM element, they just get ignored, sorry babe.) this is genuinely useful with the weird parse trees you get from basd HTML in or around FORM elements. if you need to override that behaviour, call this instead:

map HTTP::Request::Form->new($_), $tree->find_by_tag_name('FORM');

💜 INSTANCE METHODS 💜

base() — hands you back the $base parameter that you gave to the new constructor.
link() — gives you the action attribute of the original form structure. this value is cached inside the form processor, so once you've made the form processor you can safely delete the form structure. go off. 🎀
method() — gives you the method attribute of the original form structure. also cached in the form processor, so you can safely delete the form structure as soon as you've created the form processor.
isindex() — returns true if this came from an original form structure that was actually an ISINDEX element. in that case the form will have only one field: an input/text field named keywords.
name() — gives you the name attribute of the original form structure. yep, cached too, so you can safely delete the form structure after you've created the form processor.
fields() — delivers a list of fieldnames that are of the "open" type. this excludes the hidden and submit elements, because those are already filled with a value (aka declared "closed"), or — in the case of submit — they're buttons, and only one of those must be used.
allfields() — delivers a list of all the fieldnames, in the order they occured in the form-source, excluding the submit fields.
field($name [, $value]) — retrieves or sets a field-value. the field is identified by its name. you have to be sure you only put an allowed value into the field, okay? be responsible. 🙏
field_type($name) — gives you the type of the named field so you can distinguish on that type. (this is literally the only way to tell selections and radio buttons apart.)
is_selection($name) — tests whether a field is a selection or an input. radio-buttons get used the same way as standard selection fields, so is_selection returns a true value for radio buttons too! (of course, only one value is submitted for a radio button. one. single. value.) 💀
field_selection($name) — delivers the array of the options of a selection. the element marked with selected in the source is given as the default value. this works exactly the same way for radio buttons, because they're just handled as a special case of selections!
is_checkbox($name) — tells you if a field is a checkbox. if it is, there are several support methods to make use of checkboxes' special features — for example, the fact that it's only sent if it's checked. slay.
checkboxes() — delivers a list of all checkbox fields, much in the same way as the buttons method.
checkbox_check($name)
checkbox_uncheck($name)
checkbox_toggle($name) — these set, unset or toggle the checkbox checked state. checkbox values are only added to the result if they're checked. periodt.
checkbox_ischecked($name) — tells you whether a checkbox is checked or not. this matters if you want to analyze the state of fields directly after the parse.
buttons() — delivers a list of all defined and named buttons of a form.
button($button [, $value]) — gets or sets the value of a button. normally you only need the getting part. the value of a button is a reference to an array of values (because a button can exist multiple times, and we respect that).
button_type($button) — gives you the type of a button (submit/reset/image). the result is an array of type names, since a button with one name can exist multiple times.
button_exists($button) — true if the named button exists, false (undef) otherwise.
referer([$value]) — returns or sets the referer header for a request. super useful if a CGI needs a set referer for authentication. 🫶
press([$name [, $coord ] [, $number]]) — this method creates an HTTP::Request object (via HTTP::Request::Common) that sends the formdata to the server using the requested method. if you give it a button-name, that button is the one used. if you give no button name, it assumes a button without a name and just leaves out this last parameter. if the number of the button is given, that button value is delivered. if the number isn't given, 0 (the first button of this name) is assumed.

the coord parameter comes in handy when you've got an image button. if that's the case, the button press will simulate a press at coordinates [2,2] unless you provide an anonymous array with different coordinates. very demure, very mindful. 💅

dump() — dumps the form-data on stdio for debugging purposes. 🔍

🌈 SEE ALSO 🌈

HTTP::Request, HTTP::Request::Common, LWP::UserAgent, HTML::Element, URI::URL

🎀 INSTALLATION 🎀

perl Makefile.PL
make install

or see perlmodinstall. either way, you got this. ✨

⭐ REQUIRES ⭐

Perl version 5.004 or later

HTTP::Request::Common
HTML::TreeBuilder
LWP::UserAgent

🍓 VERSION 🍓

HTTP::Request::Form version 0.9, February 8th, 2001. yes she's vintage. vintage is iconic.

🧚 RESTRICTIONS 🧚

ngl, only a subset of all possible form elements are currently supported. the list of supported tags as of this version includes:

INPUT/CHECKBOX
INPUT/HIDDEN
INPUT/IMAGE
INPUT/RADIO
INPUT/RESET
INPUT/SUBMIT
INPUT/FILE
INPUT/* (are all handled as simple text entry)
OPTION
SELECT
TEXTAREA
ISINDEX

💀 BUGS 💀

okay bestie, deep breaths, here's the list:

there is currently no support for multiple selections. you can do them yourself by setting a selection to a comma-delimited list of values, though. DIY queen. 💅
multiple fields are not properly handled — only the last value is available. the exception is buttons, those are handled in the right way.
if there are several fields with the same name, you can only set the value of the first of these fields (this is especially problematic with checkboxes). it does work with buttons that have the same name, though — you can press each instance identified by number.
error-checking is currently very limited (not to say nonexistant). 😭
support for HTML 4.0 optgroup tags is missing (as it is with allmost all current browsers, so honestly not a great loss).
the button tag (HTML 4.0) is just handled as an alias for the input tag — this is of course incorrect, but it's sufficient for supporting the usual button types.

none of this is undefined behaviour or anything, it's just... limited. set your expectations accordingly, babe. 🫶

💖 COPYRIGHT 💖

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

🌟 MAJOR CONTRIBUTORS 🌟

Sean M. Burke (ISINDEX, new_many) — legend behaviour, no notes. 👑

and that's the whole page, bestie! this one's from perl v5.42.0, dated 2025-07-25, and it lives in the Form(3) section of the manual. go fill out some forms. not like that. 💖✨🦋

📦 where this page comes from

fedora 43: perl-HTTP-Request-Form 0.952-33.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms