CGI::Test::Input(3pm)

💖 CGI::Test::Input — abstract representation of POST input 💖

okay bestie, welcome to CGI::Test::Input, the little abstract glow-up of a class that models what you actually send to a server when you POST. it lives in the CGI::Test::Input(3pm) corner of your perl docs, and yes she's giving very much "behind the scenes queen" energy. let's get into it 🫶

---

✨ SYNOPSIS ✨

# Deferred class, only heirs can be created
# $input holds a CGI::Test::Input object

$input->add_widget($w);                     # done internally for you

$input->add_field("name", "value");         # manual input construction
$input->add_file("name", "path");           # deferred reading
$input->add_file_now("name", "/tmp/path");  # read file immediately

syswrite INPUT, $input->data, $input->length;   # if you really have to

# $test is a CGI::Test object
$test->POST("http://server:70/cgi-bin/script", $input);

like… look at her. so clean. so structured. we love a synopsis that eats 💅

---

🌸 DESCRIPTION 🌸

so the tea is this: CGI::Test::Input is a deferred class. it's an abstract representation of HTTP POST request input — the exact kind of input that the POST routine of CGI::Test expects. she's the blueprint, not the building. 🏗️

and honestly? if you're not out here issuing a POST request manually to hand-craft your own carefully curated input, you do not need to learn this hierarchy's interface. you don't even need to know it exists. it's giving background character who's secretly running the whole show. 😭

but IF you do want to roll your own, here's the move: decide which MIME encoding you want, and create an object of the appropriate type. heads up though — file uploading requires the multipart/form-data encoding. no substitutions, bestie. periodt.

• MIME encoding application/x-www-form-urlencoded → create a CGI::Test::Input::URL ✨
• MIME encoding multipart/form-data → create a CGI::Test::Input::Multipart 🦋

once the object exists, you can add name/value tuples that correspond to the CGI parameters you're submitting. iconic behavior.

for instance:

my $input = CGI::Test::Input::Multipart->new();
$input->add_field("login", "ram");
$input->add_field("password", "foobar");
$input->add_file("organization", "/etc/news/organization");

and then, if you want to peek at what's normally sent off to the HTTP server:

print "Content-Type: ", $input->mime_type, "\015\012";
print "Content-Length: ", $input->length, "\015\012";
print "\015\012";
print $input->data;

but realistically? usually you just hand that $input object over to the POST routine of CGI::Test and let her do her thing. main character delegation. 👑

---

🌈 INTERFACE 🌈

🎀 Creation Routine

it's called new, as usual, because of course it is. all subclasses share the same creation routine signature, and it takes no parameter. no drama, no arguments, just vibes.

🧚 Adding Parameters

CGI parameters are name/value tuples. and for file uploads, they can have content too — in that case the value is the file path on the client machine. slay.

• add_field name, value — adds the CGI parameter name, whose value is value. simple. elegant. we stan.
• add_file name, path — adds the file upload parameter name, located at path.

⚠️ the file is not read immediately, so it has to stay available until the data routine is called, at minimum. it is not an error if the file can't be read at that time, though.

when you're not using the multipart/form-data encoding, only the name/path tuple gets transmitted to the script. that's it. that's the whole send. 💀

• add_file_now name, path — same as add_file, but the file is read immediately, which means you can dispose of it afterwards. tiny catch: the file must exist. no file, no entry, no exceptions. 🫶
• add_widget widget — adds any widget, aka a CGI::Test::Form::Widget object. this routine gets called internally by CGI::Test to build the input data when you submit a form via POST. so like, she's doing it for you. you're welcome.

💜 Generation

• data — returns the data, under the proper encoding. ✨
• mime_type — returns the proper MIME encoding type, suitable for inclusion within a Content-Type header. very demure, very mindful. 🎀
• length — returns the data length. numbers. we love numbers. 🔥

---

👑 AUTHORS 👑

• the original author is Raphael Manfredi.
• Steven Hilton was long time maintainer of this module.
• current maintainer is Alexander Tokarev <tokarev@cpan.org>. 🫶

---

🦋 SEE ALSO 🦋

• CGI::Test(3)
• CGI::Test::Input::URL(3)
• CGI::Test::Input::Multipart(3)

---

and that's the whole page, bestie!! this was perl v5.34.0, dated 2022-06-10, from CGI::Test::Input(3pm) — mwah, go forth and POST responsibly 💖✨🌸