Header(3pm)

💖 Header(3pm) 💖

okay so bestie, welcome to the Header page (section 3pm, she's famous) — this is the Text::Header module and honestly? she's giving "quiet utility icon" and I'm obsessed. let's get into it ✨

---

🌸 NAME 🌸

Text::Header — the RFC 822/2068 "header" and "unheader" functions, no cap 💅

---

✨ SYNOPSIS ✨

   use Text::Header;     # header and unheader exported

   # Construct headers similar to CGI.pm and HTTP::Headers

   @HEADERS = header(content_type => 'text/html',
                     author => 'Nathan Wiger',
                     last_modified => $date,
                     accept => [qw(text/html text/plain)]);

   # The above produces the array:

   @HEADERS = ("Content-Type: text/html\n",
               "Author: Nathan Wiger\n",
               "Last-Modified: Wed Sep 27 13:31:06 PDT 2000\n",
               "Accept: text/html, text/plain\n");

   # Can also construct SMTP headers to format mail

   @mail_headers = header(from => 'Nathan Wiger <nate@sun.com>',
                          to => 'perl5-porters@perl.org');

   print $MAIL @mail_headers, "\nKeep up the great work!\n";

   # The above would print this to the $MAIL handle:

   From: Nathan Wiger <nate@sun.com>
   To: perl5-porters@perl.org

   Keep up the great work!

---

🦋 DESCRIPTION 🦋

so this module hands you two brand new functions, "header" and "unheader", and they're basically the general-purpose glue for building and parsing RFC 822 headers. 🫶

important though: they do NOT have any intelligent HTTP-specific defaults baked in. nope. they're just here to make the mechanics of header parsing easy, that's the whole job, periodt.

the output style is literally designed to mimic "CGI.pm" and "HTTP::Headers", so if you already know those interfaces you'll feel right at home. and as shown up there ^^ the "headers" function automatically does the following:

1. uc's the first letter of each tag token and lc's the rest, also converting _'s to -'s automatically
2. Adds a colon separating each tag and its value, and exactly one newline after each one
3. Combines list elements into a comma-delimited string

heads up bestie: a list is always joined into a comma-delimited string. so if you want multiple separate headers, just call "header" with multiple args like this:

   push @out, header(accept => 'text/html',
                     accept => 'text/plain');

and that would create multiple "Accept:" lines. slay. 🌈

okay now here's the thing — unlike "CGI.pm", the "header" function here has no intelligent defaults. so if you call it like:

   @out_headers = header;

it returns an empty list. and that's on purpose! it's what lets "header" be more general purpose so it can do SMTP and other headers too. you can even use it as a generic text formatting tool, which is literally why it lives under the "Text::" hierarchy. iykyk 💅

---

💜 the "unheader" function 💜

"unheader" works in exactly the opposite direction from "header" — it pulls headers apart and returns a list. "unheader":

1. lc's the entire tag name, converting -'s to _'s
2. Separates each tag based on the colon delimiter, chomping newlines.
3. Returns a list of tag/value pairs for easy assignment to a hash

so, assuming the @HEADERS array shown up top:

   %myheaders = unheader(@HEADERS);

the hash %myheaders would have the following values:

   %myheaders = (
       content_type => 'text/html',
       author => 'Nathan Wiger',
       last_modified => 'Wed Sep 27 13:31:06 PDT 2000',
       accept => 'text/html, text/plain'
   );

note that all keys get converted to lowercase, and their values have their newlines stripped. 🧚

but wait — comma-separated fields are not split up on input. and it literally cannot be done reliably, because some fields (like the HTTP "Date:" header) can contain commas even though they are not lists. inferring that kind of structure would require knowledge of content, and these functions are specifically designed to be content-independent. periodt.

---

🎀 line wrapping (SMTP girlies rise up) 🎀

the "unheader" function will respect line wrapping, like you see in SMTP headers. it just joins the lines and returns the value, so that:

   %mail = unheader("To: Nathan Wiger <nate@sun.com>,
                             perl5-porters@perl.org");

would return:

   $mail{to} = "Nathan Wiger <nate@sun.com>, perl5-porters@perl.org"

notice that multiple spaces between the comma separator have been condensed to a single space. ✨

and because the "header" and "unheader" functions are direct inverses, this call:

   @out = header unheader @in;

will result in @out being exactly equivalent to @in. the way that round-trips flawlessly... iconic. 👑

---

📚 REFERENCES 📚

this is designed as both a Perl 5 module and also a Perl 6 prototype. please see the Perl 6 proposal at http://dev.perl.org/rfc/333.html

this module is designed to be fully compliant with the internet standards RFC 822 (SMTP Headers) and RFC 2068 (HTTP Headers). no cap fr fr 🔥

---

👑 AUTHOR 👑

Copyright (c) 2000 Nathan Wiger <nate@sun.com>. All Rights Reserved.

This module is free software; you may copy this under the terms of the GNU General Public License, or the Artistic License, copies of which should have accompanied your Perl kit.

---

🫶 and that's the whole page bestie!! huge shoutout to perl v5.34.0 and its 2022-06-28 date stamp for bringing us this moment — Header(3pm) out 💖✨🎀🦋🌸💅