HTTP::M...rtParser(3)

📦
version 0.02 · 9 versions
, in opensuse-leap 16.0

🌸 NAME 🌸

HTTP::MultiPartParser — it's the HTTP MultiPart Parser, bestie. Low-level, no drama, just vibes and octets. You're reading the User Contributed Perl Documentation page for HTTP::M...rtParser(3), and yes the name is abbreviated in the header because the terminal is a hater. 💅

✨ SYNOPSIS ✨

Okay so here's the whole flow, look:

$parser = HTTP::MultiPartParser->new(
    boundary  => $boundary,
    on_header => $on_header,
    on_body   => $on_body,
);

while ($octets = read_octets_from_body()) {
    $parser->parse($octets);
}

$parser->finish;

That's it. That's the entire relationship. 🫶

🦋 DESCRIPTION 🦋

So this class is giving low-level API energy for processing MultiPart MIME data streams — the kind that conform to MultiPart types as defined in RFC 2616 <http://tools.ietf.org/html/rfc2616#section-3.7.2>. It parses, it doesn't judge. No cap. ✨

🎀 METHODS 🎀

💖 new

$parser = HTTP::MultiPartParser->new( %attributes );

This constructor returns an instance of HTTP::MultiPartParser. The valid attributes include:

  • boundary (Mandatory)
boundary => $value

This is the unquoted and unescaped boundary parameter value straight out of the Content-Type header field. Heads up: the boundary parameter value consists of a restricted set of characters as defined in RFC 2046 <http://tools.ietf.org/html/rfc2046#section-5.1.1>. The whole guest list is:

DIGIT / ALPHA / "'" / "(" / ")" /
"+" / "_" / "," / "-" / "." /
"/" / ":" / "=" / "?"

Literally only those, bestie. Don't try to sneak anything else in. 💀

  • on_header (Mandatory)
on_header => $callback->($header)

This callback gets invoked when the header of a part has successfully been received. And it's a one-time thing — the callback will only be invoked once for each part. Iconic behaviour honestly. 👑

  • on_header_as
on_header_as => 'unparsed' | 'lines'

This one defines the $header value that gets passed to the on_header callback. Two flavours, pick your fighter:

  • unparsed — the callback is invoked with an octet string containing the unparsed header. Raw. Unfiltered. Main character energy. 🦋
  • lines — the callback is invoked with an ARRAY reference, where each element of the array is a header line. Folding whitespace is removed from all lines, and header continuation lines are unwrapped. Tidy and slay. ✨
  • on_body (Mandatory)
on_body => $callback->($chunk, $final)

This callback gets invoked whenever there's any data available for the body of a part. Heads up though — it may be invoked multiple times for each part, so don't go assuming it's a one-and-done situation. It's a group chat, not a DM. 💬

  • on_error
on_error => $callback->($message)

This callback gets invoked anytime an error occurs in the parser. And fr fr, once you receive an error, the parser is no longer useful in its current state. It's done. It's over. 😭

  • max_preamble_size
max_preamble_size => 32768
  • max_header_size
max_header_size => 32768

🌈 parse

$parser->parse($octets);

Parses the given octets. That's the whole thing. Feed it octets, it parses them. 🍓

⭐ finish

$parser->finish;

Finish the parsing. Wrapping it up, closing the loop, saying goodbye. 🎀

🧚 reset

$parser->reset;

Resets the state of the parser. Fresh start, clean slate, rebranding era. 💜

🔥 is_aborted

$boolean = $parser->is_aborted;

Returns true if an error has occurred in the parser. A vibe check for your parser's wellbeing, basically. 🙈

💀 DIAGNOSTICS 💀

  • (F) Usage: %s — Method called with wrong number of arguments. You passed the wrong amount of stuff. It's giving "read the synopsis". 😭

🌸 SEE ALSO 🌸

🫶 SUPPORT 🫶

🐛 Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at <https://github.com/chansen/p5-http-multipartparser/issues>. And the best part? You will be notified automatically of any progress on your issue. Obsessed with the transparency honestly. ✨

📦 SOURCE CODE

This is open source software. The code repository is available for public review and contribution under the terms of the license.

<httsp://github.com/chansen/p5-http-multipartparser>

(Yeah, that's the URL exactly as written — httsp, not https. Not me fixing it, that's literally what it says. 🙈)

git clone https://github.com/chansen/p5-http-multipartparser

👑 AUTHOR 👑

Christian Hansen "chansen@cpan.org" — the legend themselves. 🫡

Copyright 2012-2017 by Christian Hansen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Slay, legally speaking. ⚖️✨

Okay that's the whole page, bestie — brought to you by perl v5.42.0, dated 2019-08-09, and filed under HTTP::M...rtParser(3) in your favourite User Contributed Perl Documentation. Go forth and multipart. 💜🎀🦋
📦 where this page comes from