Email::...::Header(3)

💌 NAME 💌

Email::Simple::Header — literally the header of an Email::Simple message, bestie, that's the whole vibe ✨

🎀 VERSION 🎀

version 2.218 — yes she's serving numbers 🫶

🌸 SYNOPSIS 🌸

my $email = Email::Simple->new($text);

my $header = $email->header_obj;
print $header->as_string;

okay so that's the whole flex 💅

🦋 DESCRIPTION 🦋

So this thing implements the headers of an Email::Simple object. It's a very minimal interface ngl — and mostly for private consumption at the moment, so like… don't get too attached, iykyk 🙈

⭐ PERL VERSION ⭐

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Lowkey generous of it, honestly 👑

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. So like… the bar only goes up, periodt 💀

---

🧚 METHODS 🧚

💖 new

my $header = Email::Simple::Header->new($head, \%arg);

$head is a string containing a valid email header, or a reference to such a string. Real talk: if a reference is passed in, don't expect that it won't be altered. She will touch it. She has no chill about it 😭

Valid arguments are:

• crlf — the header's newline; defaults to CRLF ✨

💜 as_string

my $string = $header->as_string(\%arg);

This returns a stringified version of the header. That's it, that's the method 🎀

🌈 header_names

This method returns a list of the unique header names found in this header, in no particular order. No order! Chaotic, free-spirited, main character energy 🦋

🍓 header_raw_pairs

my @pairs = $header->header_raw_pairs;
my $first_name  = $pairs[0];
my $first_value = $pairs[1];

This method returns a list of all the field/value pairs in the header, in the order that they appear in the header. And like — huge PSA incoming — (Remember: don't try assigning that to a hash. Some fields may appear more than once!) 🚨 bestie I am begging you, do not put that in a hash 💀

🔥 header_pairs

header_pairs is another name for header_raw_pairs, which was the original name for the method and which you'll see most often. In general, though, it's better to be explicit and use header_raw_pairs. (In Email::MIME, header_str_pairs exists for letting the library do the header decoding for you.) Glow-up arc complete ✨

👑 header_raw

my $first_value = $header->header_raw($field);
my $nth_value   = $header->header_raw($field, $index);
my @all_values  = $header->header_raw($field);

This method returns the value or values of the given header field. If the named field does not appear in the header, this method returns false. Not found = false, no cap 🙅‍♀️

🫶 header

This method just calls "header_raw". It's the older name for "header_raw", but it can be a problem because Email::MIME, a subclass of Email::Simple, makes "header" return the header's decoded value. So like… legacy naming drama, be aware 😬

💅 header_raw_set

$header->header_raw_set($field => @values);

This method updates the value of the given header. Existing headers have their values set in place. Additional headers are added at the end. If no values are given to set, the header will be removed from to the message entirely. Gone. Deleted. Blocked 🚫✨

🧚 header_set

header_set is another name for header_raw_set, which was the original name for the method and which you'll see most often. In general, though, it's better to be explicit and use header_raw_set. (In Email::MIME, header_str_set exists for letting the library do the header encoding for you.) Same energy as before, just the ✨set✨ version 🌸

💀 header_raw_prepend

$header->header_raw_prepend($field => $value);

This method adds a new instance of the name field as the first field in the header. Front of the line, first place, main character position 👑💅

🎀 header_rename

$header->header_rename($field, $new_name, $nth);

This renames the named field to the new name. If $nth is given, only the nth instance of the field will be renamed. It is fatal to rename an instance that does not exist. Like, it will die, bestie, don't test her 😭 The first instance of a header is the 0th.

If $nth is omitted, all instances of the header are renamed. Every single one 🫶

When picking headers to rename, $field is matched case insensitively. So, given this header:

happythoughts: yes
HappyThoughts: so many
hapPyThouGhts: forever

Then this code...

$header->rename_header('happythoughts', 'Delights');

...will result in this:

Delights: yes
Delights: so many
Delights: forever

Case insensitive matching ate that, fr fr 🔥

Headers may be rewrapped as a result of renaming. Little side effect, just so you know 🙈

🦋 crlf

This method returns the newline string used in the header. The newline. The string. The whole vibe 🌈

---

💜 AUTHORS 💜

• Simon Cozens
• Casey West
• Ricardo SIGNES <cpan@semiotic.systems> 🫶

🌸 COPYRIGHT AND LICENSE 🌸

This software is copyright (c) 2003 by Simon Cozens.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Free software icon behavior, we love to see it 💖

---

okay so that's the whole page, and before you go — this lil doc drop was served up by perl v5.42.0 on 2023-01-09, filed under Email::...::Header(3) 💅✨ bye bestie, go read some headers 🎀