CGI::T...tipart(3pm)

📦
version 1.003 · 2 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

✨ hi bestie, welcome ✨

you're reading the CGI::T...tipart(3pm) page, straight outta the User Contributed Perl Documentation section. it's a tiny parser page and honestly it ate. let's get into it 💅

🌸 NAME 🌸

CGI::Tiny::Multipart — Tiny multipart/form-data form parser 🦋

like. that's the whole vibe. it parses multipart/form-data. tiny-ly. 👑

🎀 SYNOPSIS 🎀

the way you literally just import the functions you want:

use CGI::Tiny::Multipart qw(extract_multipart_boundary parse_multipart_form_data);

my $boundary = extract_multipart_boundary($content_type) // die "Failed to parse multipart boundary";
my $parts = parse_multipart_form_data($fh, $content_length, $boundary) // die "Malformed multipart/form-data content";

bestie, the // die is giving "if this fails we're done here" and honestly? respect. 🫶

💖 DESCRIPTION 💖

CGI::Tiny::Multipart is a tiny "multipart/form-data" parser for CGI::Tiny, and it's based on two whole RFCs, no cap:

so it's not just vibes, it's standards-based vibes. 🌈

🔥 FUNCTIONS 🔥

the following functions are exported on request. so you have to ask for them. consent is key. 💅

💜 extract_multipart_boundary

my $boundary = extract_multipart_boundary($content_type);

extracts the multipart boundary from a "Content-Type" header. returns "undef" if the boundary was not found. 😭 (it's okay. boundaries ghost us all.)

🌟 parse_multipart_form_data

my $parts = parse_multipart_form_data($fh, $content_length, $boundary, \%options);
my $parts = parse_multipart_form_data(\$bytes, length($bytes), $boundary, \%options);

parses "multipart/form-data" request content into an ordered array reference, or returns "undef" if the request content is malformed and cannot be parsed. 💀

the input parameter may be:

  • a filehandle, which will have "binmode" applied to remove any translation layers, or
  • a scalar reference to a string containing the request content.

bytes will be read from the input up to the specified $content_length. periodt.

the following options may be specified in an optional hashref parameter:

  • buffer_size — buffer_size => 262144

buffer size (number of bytes to read at once) for reading the request body from an input filehandle. defaults to 262144 (256 KiB). a value of 0 will use the default value. so like, 0 is not "no buffer", it's "surprise, default". 🎀

  • parse_as_files — parse_as_files => 1 / parse_as_files => 0

if set to a true value, all form field values will be parsed as file uploads, calling "on_file_buffer" or storing the contents in a tempfile. if set to a false (but defined) value, all form field values will be returned as "content", even file uploads. by default, text field values will be returned as "content" and file uploads will be parsed by "on_file_buffer" or stored in tempfiles. ✨ (note the defined part — undef is not 0, bestie, don't play yourself.)

  • on_file_buffer — on_file_buffer => sub { my ($bytes, $hashref, $eof) = @_; }

callback for custom parsing of file upload form fields. if specified, it will be called with each (possibly empty) chunk of file contents that is read from the form as bytes. the hash reference representing this form field is passed as the second argument. the third argument will be true the last time the callback is called for a particular form field. 👑

the hash reference passed to the callback persists between calls for the same form field, and is the same hash reference that will ultimately be returned to represent the form field. it will contain the "headers", undecoded "name" and "filename", and "size" of contents read so far (including the bytes just passed to the callback).

modifying these values may result in unexpected behavior, but other modifications to the hash reference are allowed. 🙈 so like, touch the other keys, not those ones.

if "on_file_buffer" is not specified, file uploads will be stored in "file" as a File::Temp object created with "tempfile_args".

# approximate the default behavior
on_file_buffer => sub {
  my ($bytes, $hashref, $eof) = @_;
  $hashref->{file} //= File::Temp->new;
  print {$hashref->{file}} $bytes;
  if ($eof) {
    $hashref->{file}->flush;
    seek $hashref->{file}, 0, 0;
  }
}

look at that little //= doing the "create it only if it's not there yet" move. iconic. 🧚

  • tempfile_args — tempfile_args => [TEMPLATE => 'tempXXXXX', SUFFIX => '.dat']

arguments to pass to the File::Temp constructor when creating tempfiles for file uploads. by default no arguments are passed. not used if a custom "on_file_buffer" callback is passed. so pick a lane, bestie. 🎀

  • discard_files — discard_files => 1

if set to a true value, file upload field contents will be discarded without calling "on_file_buffer", and neither "content" nor "file" will be provided for those form fields. 💀 note that this discards the contents of form fields with a defined "filename" regardless of the "parse_as_files" setting. yeah. regardless. read it again. 🫶

🌈 form fields, explained 🌈

form fields are represented as hash references containing:

  • headers — hash reference of form field headers. header names are represented in lowercase.
  • name — form field name from "Content-Disposition" header, undecoded.
  • filename — filename from "Content-Disposition" header if present, undecoded.
  • size — size of form field contents in bytes. 📏
  • content — form field contents as undecoded bytes, for form fields without a defined "filename", or for all form fields if the "parse_as_files" option was set to a false value. file uploads are stored in a temporary "file" instead by default.
  • file — File::Temp object referencing temporary file containing the form field contents, for form fields with a defined "filename", or for all form fields if the "parse_as_files" option was set to a true value.

🦋 BUGS 🦋

report any issues on the public bugtracker. (not in my DMs, bestie, the bugtracker. 💅)

👑 AUTHOR 👑

Dan Book <dbook@cpan.org> — ty king 🫶

this software is Copyright (c) 2021 by Dan Book.

this is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

⭐ SEE ALSO ⭐

  • HTTP::Body::MultiPart

go read that one too, iykyk. ✨

and that's the whole page, bestie — this was perl v5.38.2, dated 2024-06-15, and yes it's the CGI::T...tipart(3pm) one. now go parse something. 💖🎀🦋

📦 where this page comes from