Email::Address::XS(3)

📦
version 1.05 · 13 versions
, in opensuse-leap 16.0

🎀 Email::Address::XS(3) 🎀

User Contributed Perl Documentation — yes bestie, that's the header energy. Buckle up, we're doing RFC email addresses and it's gonna be iconic.

💖 NAME 💖

Email::Address::XS — parse and format RFC 5322 email addresses and groups. Literally what it says on the tin, no cap. 🦋

✨ SYNOPSIS ✨

Okay so here's the whole vibe in code:

  use Email::Address::XS;

  my $winstons_address = Email::Address::XS->new(phrase => 'Winston Smith', user => 'winston.smith', host => 'recdep.minitrue', comment => 'Records Department');
  print $winstons_address->address();
  # winston.smith@recdep.minitrue

  my $julias_address = Email::Address::XS->new('Julia', 'julia@ficdep.minitrue');
  print $julias_address->format();
  # Julia <julia@ficdep.minitrue>

  my $users_address = Email::Address::XS->parse('user <user@oceania>');
  print $users_address->host();
  # oceania

  my $goldsteins_address = Email::Address::XS->parse_bare_address('goldstein@brotherhood.oceania');
  print $goldsteins_address->user();
  # goldstein

  my @addresses = Email::Address::XS->parse('"Winston Smith" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>');
  # ($winstons_address, $julias_address)

  use Email::Address::XS qw(format_email_addresses format_email_groups parse_email_addresses parse_email_groups);

  my $addresses_string = format_email_addresses($winstons_address, $julias_address, $users_address);
  # "Winston Smith" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>, user <user@oceania>

  my @addresses = map { $_->address() } parse_email_addresses($addresses_string);
  # ('winston.smith@recdep.minitrue', 'julia@ficdep.minitrue', 'user@oceania')

  my $groups_string = format_email_groups('Brotherhood' => [ $winstons_address, $julias_address ], undef() => [ $users_address ]);
  # Brotherhood: "Winston Smith" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>;, user <user@oceania>

  my @groups = parse_email_groups($groups_string);
  # ('Brotherhood' => [ $winstons_address, $julias_address ], undef() => [ $users_address ])

  use Email::Address::XS qw(compose_address split_address);

  my ($user, $host) = split_address('julia(outer party)@ficdep.minitrue');
  # ('julia', 'ficdep.minitrue')

  my $string = compose_address('charrington"@"shop', 'thought.police.oceania');
  # "charrington\"@\"shop"@thought.police.oceania

🌸 DESCRIPTION 🌸

Okay so this module implements an RFC 5322 (https://tools.ietf.org/html/rfc5322) parser and formatter for email addresses and groups. It parses an input string from email headers that contain a list of email addresses or groups of email addresses (like From, To, Cc, Bcc, Reply-To, Sender, ...). It can also generate a string value for those headers from a list of email address objects. The module is backward compatible with RFC 2822 (https://tools.ietf.org/html/rfc2822) and RFC 822 (https://tools.ietf.org/html/rfc822). 💌

Parser and formatter functionality is implemented in XS and uses shared code from the Dovecot IMAP server. Native speed, bestie — we love to see it. ✨

It is a drop-in replacement for the Email::Address module, which has several security issues. E.g. issue CVE-2015-7686 (Algorithmic complexity vulnerability) — https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-7686 — which allows remote attackers to cause denial of service, is still present in Email::Address version 1.908. Yeah, that's a yikes. 💀

The Email::Address::XS module was created to finally fix CVE-2015-7686. Periodt.

Existing applications that use the Email::Address module could be easily switched to the Email::Address::XS module. In most cases, only changing use Email::Address to use Email::Address::XS and replacing every Email::Address occurrence with Email::Address::XS is sufficient. Glow-up complete. 💅

So unlike Email::Address, this module does not use regular expressions for parsing; instead, the native XS implementation parses the input string sequentially according to RFC 5322 grammar. It's giving structured, sequential, no-regex chaos. 🦋

Additionally, it has support also for named groups and so can be used instead of the Email::Address::List module.

If you are looking for the module which provides object representation for the list of email addresses suitable for the MIME email headers, see Email::MIME::Header::AddressList.

💅 EXPORT 💅

None by default. Exportable functions are: parse_email_addresses, parse_email_groups, format_email_addresses, format_email_groups, compose_address, split_address.

🎀 Exportable Functions 🎀

format_email_addresses

  use Email::Address::XS qw(format_email_addresses);

  my $winstons_address = Email::Address::XS->new(phrase => 'Winston Smith', address => 'winston@recdep.minitrue');
  my $julias_address = Email::Address::XS->new(phrase => 'Julia', address => 'julia@ficdep.minitrue');
  my @addresses = ($winstons_address, $julias_address);
  my $string = format_email_addresses(@addresses);
  print $string;
  # "Winston Smith" <winston@recdep.minitrue>, Julia <julia@ficdep.minitrue>

Takes a list of email address objects and returns one formatted string of those email addresses. You hand it the little address objects, it hands you back the header-ready string. Slay. 💖

format_email_groups

  use Email::Address::XS qw(format_email_groups);

  my $winstons_address = Email::Address::XS->new(phrase => 'Winston Smith', user => 'winston.smith', host => 'recdep.minitrue');
  my $julias_address = Email::Address::XS->new('Julia', 'julia@ficdep.minitrue');
  my $users_address = Email::Address::XS->new(address => 'user@oceania');

  my $groups_string = format_email_groups('Brotherhood' => [ $winstons_address, $julias_address ], undef() => [ $users_address ]);
  print $groups_string;
  # Brotherhood: "Winston Smith" <winston.smith@recdep.minitrue>, Julia <julia@ficdep.minitrue>;, user@oceania

  my $undisclosed_string = format_email_groups('undisclosed-recipients' => []);
  print $undisclosed_string;
  # undisclosed-recipients:;

Like format_email_addresses, but this method takes pairs which consist of a group display name and a reference to an address list. If a group is not undef, then the address list is formatted inside a named group. Group-chat energy, but make it email headers. 🫶

parse_email_addresses

  use Email::Address::XS qw(parse_email_addresses);

  my $string = '"Winston Smith" <winston.smith@recdep.minitrue>, Julia <julia@ficdep.minitrue>, user@oceania';
  my @addresses = parse_email_addresses($string);
  # @addresses now contains three Email::Address::XS objects, one for each address

Parses an input string and returns a list of Email::Address::XS objects. Optional second string argument specifies the class name for blessing new objects. Cute, flexible, and very much in its main character era. ✨

parse_email_groups

  use Email::Address::XS qw(parse_email_groups);

  my $string = 'Brotherhood: "Winston Smith" <winston.smith@recdep.minitrue>, Julia <julia@ficdep.minitrue>;, user@oceania, undisclosed-recipients:;';
  my @groups = parse_email_groups($string);
  # @groups now contains list ('Brotherhood' => [ $winstons_object, $julias_object ], undef() => [ $users_object ], 'undisclosed-recipients' => [])

Like parse_email_addresses, but this function returns a list of pairs: a group display name and a reference to a list of addresses which belongs to that named group. An undef value for a group means that a following list of addresses is not inside any named group. An output is in the same format as an input for the function format_email_groups. This function preserves order of groups and does not do any de-duplication or merging. Faithful round-trip, no notes. 💅

compose_address

  use Email::Address::XS qw(compose_address);
  my $string_address = compose_address($user, $host);

Takes an unescaped user part and unescaped host part of an address and returns the escaped address.

Available since version 1.01.

split_address

  use Email::Address::XS qw(split_address);
  my ($user, $host) = split_address($string_address);

Takes an escaped address and splits it into a pair of unescaped user part and unescaped host part of address. If splitting the input address into these two parts is not possible, then this function returns a pair of undefs.

Available since version 1.01.

👑 Class Methods 👑

new

  my $empty_address = Email::Address::XS->new();
  my $winstons_address = Email::Address::XS->new(phrase => 'Winston Smith', user => 'winston.smith', host => 'recdep.minitrue', comment => 'Records Department');
  my $julias_address = Email::Address::XS->new('Julia', 'julia@ficdep.minitrue');
  my $users_address = Email::Address::XS->new(address => 'user@oceania');
  my $only_name = Email::Address::XS->new(phrase => 'Name');
  my $copy_of_winstons_address = Email::Address::XS->new(copy => $winstons_address);

Constructs and returns a new Email::Address::XS object. Takes a named list of arguments: phrase, address, user, host, comment, and copy. An argument address takes precedence over user and host.

When an argument copy is specified, then it is expected to be an Email::Address::XS object and a cloned copy of that object is returned. All other parameters are ignored.

Old syntax from the Email::Address module is supported too. Takes one to four positional arguments: phrase, address, comment, and the original string. Passing an argument original is deprecated, ignored, and throws a warning. 🫶

parse

  my $winstons_address = Email::Address::XS->parse('"Winston Smith" <winston.smith@recdep.minitrue> (Records Department)');
  my @users_addresses = Email::Address::XS->parse('user1@oceania, user2@oceania');

Parses an input string and returns a list of Email::Address::XS objects. Same as the function parse_email_addresses, but this one is a class method.

In scalar context this function returns just the first parsed object. If more than one object was parsed, then the is_valid method on the returned object returns false. If no object was parsed, then an empty Email::Address::XS object is returned.

Prior to version 1.01, the return value in scalar context is undef when no object was parsed.

parse_bare_address

  my $winstons_address = Email::Address::XS->parse_bare_address('winston.smith@recdep.minitrue');

Parses an input string as one bare email address (addr spec) which does not allow a phrase part or angle brackets around the email address, and returns an Email::Address::XS object. It is just a wrapper around the address method. The is_valid method can be used to check if parsing was successful.

Available since version 1.01.

🦋 Object Methods 🦋

format

  my $string = $address->format();

Returns a formatted Email::Address::XS object as a string. This method throws a warning when the user or host part of the email address is invalid or an empty string. Heads up, bestie — keep those parts valid. 💖

is_valid

  my $is_valid = $address->is_valid();

Okay so is_valid returns true if the parse function or method that created this Email::Address::XS object had zero syntax errors on the input string, and also if the user and host parts of the email address aren't empty strings. No cap.

So basically it's your vibe check before you call format on the object. Useful! Available since version 1.01.

phrase 🎀

my $phrase = $address->phrase();
$address->phrase('Winston Smith');

Accessor and mutator for the phrase, aka the display name. Bestie behavior.

user 🦋

my $user = $address->user();
$address->user('winston.smith');

Accessor and mutator for the unescaped user part of an address — the local/mailbox part. iykyk

host 🌸

my $host = $address->host();
$address->host('recdep.minitrue');

Accessor and mutator for the unescaped host part of an address — the domain part. Main character energy.

Since version 1.03 this method checks if setting a new value is syntactically valid. If it's not, undef is set and returned. So watch out for that.

address 💌

my $string_address = $address->address();
$address->address('winston.smith@recdep.minitrue');

Accessor and mutator for the escaped address — the addr spec. Iconic.

Internally this module stores a user and a host part of an address separately. Function compose_address is used for composing the full address, and function split_address is used for splitting into a user and a host parts. If splitting the new address into these two parts is not possible, then this method returns undef and sets both parts to undef. Noted, fr fr.

comment 🍓

my $comment = $address->comment();
$address->comment('Records Department');

Accessor and mutator for the comment which is formatted after an address. A comment can contain another nested comments in round brackets. When setting a new comment, this method checks if the brackets are balanced. If they're not, undef is set and returned. Bracket balance is the vibe check here.

name ✨

my $name = $address->name();

This method tries to return a name which belongs to the address. It returns either the phrase or comment or user part of the address or an empty string — first defined value in this order. But it never returns undef. Never! Periodt.

as_string 👑

my $address = Email::Address::XS->new(phrase => 'Winston Smith', address => 'winston.smith@recdep.minitrue');
my $stringified = $address->as_string();

This method is used for object stringification. It returns a string representation of the object. By default the object is stringified to format. Available since version 1.01.

original 🧚

my $address = Email::Address::XS->parse('(Winston) "Smith"   <winston.smith@recdep.minitrue> (Minitrue)');
my $original = $address->original();
# (Winston) "Smith"   <winston.smith@recdep.minitrue> (Minitrue)
my $format = $address->format();
# Smith <winston.smith@recdep.minitrue> (Minitrue)

This method returns the original part of the string which was used for parsing the current Email::Address::XS object. If the object was not created by parsing an input string, then this method returns undef. Lowkey important.

Note that the format method does not have to return the same original string. Available since version 1.01. Obsessed with the receipts.

💅 Overloaded Operators 💅

stringify

my $address = Email::Address::XS->new(phrase => 'Winston Smith', address => 'winston.smith@recdep.minitrue');
print "Winston's address is $address.";
# Winston's address is "Winston Smith" <winston.smith@recdep.minitrue>.

Stringification is done by method as_string. Slay.

💀 Deprecated Functions and Variables 💀

For compatibility with the Email::Address module there are defined some deprecated functions and variables. Do not use them in new code. Their usage throws warnings. You've been warned, bestie.

Altering deprecated variable $Email::Address::XS::STRINGIFY changes the method which is called for objects stringification.

Deprecated cache functions purge_cache, disable_cache and enable_cache are noop and do nothing. Literally nothing.

🌈 SEE ALSO 🌈

Go read the lore, iykyk.

👑 AUTHOR 👑

Pali <pali@cpan.org> — the icon behind this whole thing. Respect.

Copyright (C) 2015-2018 by Pali <pali@cpan.org>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.0 or, at your option, any later version of Perl 5 you may have available. Free software, free vibes.

Dovecot parser is licensed under The MIT License and copyrighted by Dovecot authors. Credit where it's due.

And that's the whole page, bestie. Footer tea for the record: this one's from perl v5.42.0, dated 2022-08-08, page Email::Address::XS(3). Mwah 💋✨

📦 where this page comes from