Email::...essList(3)

📦
version 1.954.0 · 10 versions
, in opensuse-leap 16.0

💅 NAME 💅

ok so bestie, you're looking at Email::MIME::Header::AddressList — it's the MIME support for a whole list of Email::Address::XS objects. like, one address? cute. a whole list with groups and MIME encoding? that's the main character energy we're serving here 👑

✨ VERSION ✨

version 1.954 — yes, she's on 1.954, she's thriving, no cap.

🦋 SYNOPSIS 🦋

okay, here's the whole vibe in code, and bestie I kept it character for character because that's the whole point:

my $address1 = Email::Address::XS->new('Name1' => 'address1@host.com');
my $address2 = Email::Address::XS->new("Name2 \N{U+263A}" => 'address2@host.com');
my $mime_address = Email::Address::XS->new('=?UTF-8?B?TmFtZTIg4pi6?=' => 'address2@host.com');

my $list1 = Email::MIME::Header::AddressList->new($address1, $address2);

$list1->append_groups('undisclosed-recipients' => []);

$list1->first_address();
# returns $address1

$list1->groups();
# returns (undef, [ $address1, $address2 ], 'undisclosed-recipients', [])

$list1->as_string();
# returns 'Name1 <address1@host.com>, "Name2 ☺" <address2@host.com>, undisclosed-recipients:;'

$list1->as_mime_string();
# returns 'Name1 <address1@host.com>, =?UTF-8?B?TmFtZTIg4pi6?= <address2@host.com>, undisclosed-recipients:;'

my $list2 = Email::MIME::Header::AddressList->new_groups(Group => [ $address1, $address2 ]);

$list2->append_addresses($address2);

$list2->addresses();
# returns ($address2, $address1, $address2)

$list2->groups();
# returns (undef, [ $address2 ], 'Group', [ $address1, $address2 ])

my $list3 = Email::MIME::Header::AddressList->new_mime_groups('=?UTF-8?B?4pi6?=' => [ $mime_address ]);
$list3->as_string();
# returns '☺: "Name2 ☺" <address2@host.com>;'

my $list4 = Email::MIME::Header::AddressList->from_string('Name1 <address1@host.com>, "Name2 ☺" <address2@host.com>, undisclosed-recipients:;');
my $list5 = Email::MIME::Header::AddressList->from_string('Name1 <address1@host.com>', '"Name2 ☺" <address2@host.com>', 'undisclosed-recipients:;');

my $list6 = Email::MIME::Header::AddressList->from_mime_string('Name1 <address1@host.com>, =?UTF-8?B?TmFtZTIg4pi6?= <address2@host.com>, undisclosed-recipients:;');
my $list7 = Email::MIME::Header::AddressList->from_mime_string('Name1 <address1@host.com>', '=?UTF-8?B?TmFtZTIg4pi6?= <address2@host.com>', 'undisclosed-recipients:;');

see how the ☺ survives?? iconic. 🎀

💖 DESCRIPTION 💖

so this module is literally the object representation for a list of Email::Address::XS objects. like it takes your little address babies and holds them all together in one gorgeous container.

it gives you methods for RFC 2047 (<https://tools.ietf.org/html/rfc2047>) MIME encoding and decoding — and those are suitable for the RFC 2822 (<https://tools.ietf.org/html/rfc2822>) address-list structure. so the encoding/decoding is doing the work so you don't have to, periodt. 💅

🌸 EXPORT 🌸

None. that's it. nothing exported. she gives you nothing and she's still the moment. 🫶

👑 Class Methods 👑

okay so these are the "make a new one" methods, the birthing suite if you will:

  • new_empty — constructs a brand new empty Email::MIME::Header::AddressList object. blank slate, fresh start, main character origin story ✨
  • new — constructs a new Email::MIME::Header::AddressList object from a list of Email::Address::XS objects. hand her your addresses, she'll make it cute.
  • new_groups — constructs a new Email::MIME::Header::AddressList object from named groups of Email::Address::XS objects. now they're in little friend groups 💜
  • new_mime_groups — same energy as new_groups, except in this method the group names and the objects' properties are expected to be already MIME encoded, so they're ASCII strings. iykyk — don't double-encode, bestie 😭
  • from_string — constructs a new Email::MIME::Header::AddressList object from the input string arguments. it calls Email::Address::XS::parse_email_groups to do the parsing ✨
  • from_mime_string — like from_string, but the input string arguments are expected to be already MIME encoded.

🦋 Object Methods 🦋

and these are the "what can she do" methods, the moment she gets to shine:

  • as_string — returns the string representation of the Email::MIME::Header::AddressList object. calls Email::Address::XS::format_email_groups. 🔥
  • as_mime_string — like as_string, but the output string comes back properly and unambiguously MIME encoded. the MIME encoding happens before calling Email::Address::XS::format_email_groups. obsessed with the ordering ngl 💅
  • first_address — returns the first Email::Address::XS object. first is the worst, but here she's the one you asked for 🎀
  • addresses — returns the list of all the Email::Address::XS objects. the whole squad 💖
  • groups — like addresses, but returns the objects with named groups. friend groups included, no extra charge 🫶
  • append_addresses — appends Email::Address::XS objects. more friends, more fun 🌈
  • append_groups — like append_addresses, but the arguments are pairs of the name of the group and an array reference of Email::Address::XS objects. so it's name => [ ...addresses ], you got this 🧚

⭐ PERL VERSION ⭐

this library should run on perls released even a long time ago. like, she should work on any version of perl released in the last five years. 💀

although it may work on older versions of perl, there's no guarantee that the minimum required version won't be increased. the version may be increased for any reason, and there's no promise that patches will be accepted to lower the minimum required perl. so don't come for her about backwards compat, she said what she said 🙈

🌈 SEE ALSO 🌈

go off, read more:

🎀 AUTHOR 🎀

Pali <pali@cpan.org> — the icon who made this happen 👑

💜 AUTHORS 💜

  • Ricardo SIGNES <cpan@semiotic.systems>
  • Casey West <casey@geeknest.com>
  • Simon Cozens <simon@cpan.org>

this software is copyright (c) 2004 by Simon Cozens and Casey West. 🫶

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, honestly.

and that's the whole page bestie! 💖 this one came to you courtesy of perl v5.42.0, dated 2024-05-03, and the header up top got a lil squished into Email::...essList(3) — but you and me both know the real name is Email::MIME::Header::AddressList. mwah 💋✨
📦 where this page comes from