Courri...Headers(3pm)

💌 NAME 💌

Courriel::Headers — bestie, this is the headers for an email part. that's it, that's the vibe. 🎀

✨ VERSION ✨

version 0.49 — yes she's got a version number and yes she's proud of it 💅

🌸 SYNOPSIS 🌸

okay so here's the whole thing in action, look:

my $email = Courriel->parse( text => ... );
my $headers = $email->headers;

print "$_\n" for $headers->get('Received');

that's literally it. parse, grab the headers, print every Received line. iconic behaviour. 🦋

---

💖 DESCRIPTION 💖

So this class? She represents the headers of an email. That's her whole job and she ate. 🔥

Here's the thing though — any sub part of an email can have its own headers, so every single part gets its own little object holding its headers. And this class does not make any distinction between top-level headers and headers for a sub part. Same class, same energy, no favourites. 💜

Every individual header name/value pair is represented internally by a Courriel::Header object. Some headers are special enough to get their own subclass, because main character energy runs in the family:

• Content-Type — stored as a Courriel::Header::ContentType object.
• Content-Disposition — stored as a Courriel::Header::Disposition object.

---

🎀 API 🎀

This class supports the following methods, and bestie, there are a few. grab a snack. 🍓

Courriel::Headers->parse( ... )

This one makes a brand new object by parsing a string. She accepts the following parameters:

• text — the text to parse, okay? And listen: this can either be a plain scalar or a reference to a scalar. And if you pass a reference, heads up — the underlying scalar may be modified. so like. don't be precious about it. 😭

Header parsing unfolds folded headers, and decodes any MIME-encoded values as described in RFC 2047. Parsing also decodes header attributes encoded as described in RFC 2231. she does all of that for you, no cap. ✨

Courriel::Headers->new( headers => [ ... ] )

This one makes a new object. She accepts one parameter, headers, which should be an array reference of header names and values.

A given header key can appear multiple times. yeah, she's chill like that. 💅

This object does not (yet, perhaps) enforce RFC restrictions on repetition of certain headers. ngl she's just not policing you right now. 🙈

Header order is preserved, per RFC 5322. periodt. 👑

$headers->get($name)

Give her a header name and she returns a list of the Courriel::Header objects found for that header. Every single occurrence of the header comes back as its own separate object. one for one, no bundling. 🫶

$headers->get_values($name)

Same deal, give her a header name, she returns a list of the string values found for that header. Each occurrence of the header is returned as a separate string. 💚

$headers->add( $name => $value )

Give her a header name and a value and she adds the headers to the object. And here's the cute detail: if any of the headers already have values in the object, then new values get added after the existing values, rather than at the end of headers. she's polite like that, she doesn't just yeet them to the back. ✨

The value can be provided as a string or a Courriel::Header object. either works, she's flexible. 🌈

$headers->unshift( $name => $value )

This is like add(), but this one pushes the headers onto the front of the internal headers array. Which is super useful if you're adding Received headers, because per RFC 5322, those should always be added at the top of the headers. front of the line, babe. 👑

The value can be provided as a string or a Courriel::Header object. 💜

$headers->remove($name)

Give her a header name and she removes all instances of that header from the object. every last one. gone. poof. 💀

$headers->replace( $name => $value )

A shortcut for calling remove() and add(). two steps, one call, efficiency queen. 💅

The value can be provided as a string or a Courriel::Header object.

$headers->as_string( skip => ...., charset => ... )

This returns a string representing the headers in the object. The values will be folded and/or MIME-encoded as needed. ✨

• skip — should be an array reference containing the name of headers that should be skipped. This parameter is optional, and the default is to include all headers. so if you don't say anything, everybody's invited. 🎀
• charset — specifies what character set to use for MIME-encoding non-ASCII values. This defaults to utf8. The charset name must be one recognized by the Encode module. and btw, MIME encoding is always done using the B (Base64) encoding, never the Q encoding. B or nothing, bestie. 💜

$headers->stream_to( output => $output, skip => ...., charset => ... )

This method will send the stringified headers to the specified output. 🌊

See the as_string() method for documentation on the skip and charset parameters. same rules, same defaults, no surprises. 🦋

---

🌟 ROLES 🌟

This class does the Courriel::Role::Streams role. she's got range. 💅

---

🆘 SUPPORT 🆘

Bugs may be submitted at <https://github.com/houseabsolute/Courriel/issues>. tell them everything, they want to know. 🐛

I am also usually active on IRC as 'autarch' on irc://irc.perl.org. come say hi, iykyk. 💬

---

📂 SOURCE 📂

The source code repository for Courriel can be found at <https://github.com/houseabsolute/Courriel>. go look, it's giving open source excellence. 🌈

---

👑 AUTHOR 👑

Dave Rolsky <autarch@urth.org> — the legend themselves. 🫶

---

💖 COPYRIGHT AND LICENSE 💖

This software is Copyright (c) 2021 by Dave Rolsky.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

The full text of the license can be found in the LICENSE file included with this distribution. read it, bestie, it's literally right there. 📜

---

and that's a wrap on Courriel::Headers, page 3pm, brought to you by perl v5.32.1, dated 2021-08-22 — she's been serving headers since way back and she's still that girl. mwah. 💋✨