.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Email::Address::XS 3"
.TH Email::Address::XS 3 "2022-08-07" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Email::Address::XS \- Parse and format RFC 5322 email addresses and groups
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Email::Address::XS;
\&
\&  my $winstons_address = Email::Address::XS\->new(phrase => \*(AqWinston Smith\*(Aq, user => \*(Aqwinston.smith\*(Aq, host => \*(Aqrecdep.minitrue\*(Aq, comment => \*(AqRecords Department\*(Aq);
\&  print $winstons_address\->address();
\&  # winston.smith@recdep.minitrue
\&
\&  my $julias_address = Email::Address::XS\->new(\*(AqJulia\*(Aq, \*(Aqjulia@ficdep.minitrue\*(Aq);
\&  print $julias_address\->format();
\&  # Julia <julia@ficdep.minitrue>
\&
\&  my $users_address = Email::Address::XS\->parse(\*(Aquser <user@oceania>\*(Aq);
\&  print $users_address\->host();
\&  # oceania
\&
\&  my $goldsteins_address = Email::Address::XS\->parse_bare_address(\*(Aqgoldstein@brotherhood.oceania\*(Aq);
\&  print $goldsteins_address\->user();
\&  # goldstein
\&
\&  my @addresses = Email::Address::XS\->parse(\*(Aq"Winston Smith" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>\*(Aq);
\&  # ($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);
\&  # (\*(Aqwinston.smith@recdep.minitrue\*(Aq, \*(Aqjulia@ficdep.minitrue\*(Aq, \*(Aquser@oceania\*(Aq)
\&
\&  my $groups_string = format_email_groups(\*(AqBrotherhood\*(Aq => [ $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);
\&  # (\*(AqBrotherhood\*(Aq => [ $winstons_address, $julias_address ], undef() => [ $users_address ])
\&
\&
\&  use Email::Address::XS qw(compose_address split_address);
\&
\&  my ($user, $host) = split_address(\*(Aqjulia(outer party)@ficdep.minitrue\*(Aq);
\&  # (\*(Aqjulia\*(Aq, \*(Aqficdep.minitrue\*(Aq)
\&
\&  my $string = compose_address(\*(Aqcharrington"@"shop\*(Aq, \*(Aqthought.police.oceania\*(Aq);
\&  # "charrington\e"@\e"shop"@thought.police.oceania
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements \s-1RFC 5322\s0 <https://tools.ietf.org/html/rfc5322>
parser and formatter of email addresses and groups. It parses an input
string from email headers which contain a list of email addresses or
a groups of email addresses (like From, To, Cc, Bcc, Reply-To, Sender,
\&...). Also it can generate a string value for those headers from a
list of email addresses objects. Module is backward compatible with
\&\s-1RFC 2822\s0 <https://tools.ietf.org/html/rfc2822> and
\&\s-1RFC 822\s0 <https://tools.ietf.org/html/rfc822>.
.PP
Parser and formatter functionality is implemented in \s-1XS\s0 and uses
shared code from Dovecot \s-1IMAP\s0 server.
.PP
It is a drop-in replacement for the Email::Address module
which has several security issues. E.g. issue \s-1CVE\-2015\-7686\s0 (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.
.PP
Email::Address::XS module was created to finally fix \s-1CVE\-2015\-7686.\s0
.PP
Existing applications that use Email::Address module could be easily
switched to Email::Address::XS module. In most cases only changing
\&\f(CW\*(C`use Email::Address\*(C'\fR to \f(CW\*(C`use Email::Address::XS\*(C'\fR and replacing every
\&\f(CW\*(C`Email::Address\*(C'\fR occurrence with \f(CW\*(C`Email::Address::XS\*(C'\fR is sufficient.
.PP
So unlike Email::Address, this module does not use
regular expressions for parsing but instead native \s-1XS\s0 implementation
parses input string sequentially according to \s-1RFC 5322\s0 grammar.
.PP
Additionally it has support also for named groups and so can be use
instead of the Email::Address::List module.
.PP
If you are looking for the module which provides object representation
for the list of email addresses suitable for the \s-1MIME\s0 email headers,
see Email::MIME::Header::AddressList.
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None by default. Exportable functions are:
\&\f(CW\*(C`parse_email_addresses\*(C'\fR,
\&\f(CW\*(C`parse_email_groups\*(C'\fR,
\&\f(CW\*(C`format_email_addresses\*(C'\fR,
\&\f(CW\*(C`format_email_groups\*(C'\fR,
\&\f(CW\*(C`compose_address\*(C'\fR,
\&\f(CW\*(C`split_address\*(C'\fR.
.SS "Exportable Functions"
.IX Subsection "Exportable Functions"
.IP "format_email_addresses" 4
.IX Item "format_email_addresses"
.Vb 1
\&  use Email::Address::XS qw(format_email_addresses);
\&
\&  my $winstons_address = Email::Address::XS\->new(phrase => \*(AqWinston Smith\*(Aq, address => \*(Aqwinston@recdep.minitrue\*(Aq);
\&  my $julias_address = Email::Address::XS\->new(phrase => \*(AqJulia\*(Aq, address => \*(Aqjulia@ficdep.minitrue\*(Aq);
\&  my @addresses = ($winstons_address, $julias_address);
\&  my $string = format_email_addresses(@addresses);
\&  print $string;
\&  # "Winston Smith" <winston@recdep.minitrue>, Julia <julia@ficdep.minitrue>
.Ve
.Sp
Takes a list of email address objects and returns one formatted string
of those email addresses.
.IP "format_email_groups" 4
.IX Item "format_email_groups"
.Vb 1
\&  use Email::Address::XS qw(format_email_groups);
\&
\&  my $winstons_address = Email::Address::XS\->new(phrase => \*(AqWinston Smith\*(Aq, user => \*(Aqwinston.smith\*(Aq, host => \*(Aqrecdep.minitrue\*(Aq);
\&  my $julias_address = Email::Address::XS\->new(\*(AqJulia\*(Aq, \*(Aqjulia@ficdep.minitrue\*(Aq);
\&  my $users_address = Email::Address::XS\->new(address => \*(Aquser@oceania\*(Aq);
\&
\&  my $groups_string = format_email_groups(\*(AqBrotherhood\*(Aq => [ $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(\*(Aqundisclosed\-recipients\*(Aq => []);
\&  print $undisclosed_string;
\&  # undisclosed\-recipients:;
.Ve
.Sp
Like \f(CW\*(C`format_email_addresses\*(C'\fR but this
method takes pairs which consist of a group display name and a
reference to address list. If a group is not undef then address
list is formatted inside named group.
.IP "parse_email_addresses" 4
.IX Item "parse_email_addresses"
.Vb 1
\&  use Email::Address::XS qw(parse_email_addresses);
\&
\&  my $string = \*(Aq"Winston Smith" <winston.smith@recdep.minitrue>, Julia <julia@ficdep.minitrue>, user@oceania\*(Aq;
\&  my @addresses = parse_email_addresses($string);
\&  # @addresses now contains three Email::Address::XS objects, one for each address
.Ve
.Sp
Parses an input string and returns a list of Email::Address::XS
objects. Optional second string argument specifies class name for
blessing new objects.
.IP "parse_email_groups" 4
.IX Item "parse_email_groups"
.Vb 1
\&  use Email::Address::XS qw(parse_email_groups);
\&
\&  my $string = \*(AqBrotherhood: "Winston Smith" <winston.smith@recdep.minitrue>, Julia <julia@ficdep.minitrue>;, user@oceania, undisclosed\-recipients:;\*(Aq;
\&  my @groups = parse_email_groups($string);
\&  # @groups now contains list (\*(AqBrotherhood\*(Aq => [ $winstons_object, $julias_object ], undef() => [ $users_object ], \*(Aqundisclosed\-recipients\*(Aq => [])
.Ve
.Sp
Like \f(CW\*(C`parse_email_addresses\*(C'\fR 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 a same format as a
input for the function \f(CW\*(C`format_email_groups\*(C'\fR.
This function preserves order of groups and does not do any
de-duplication or merging.
.IP "compose_address" 4
.IX Item "compose_address"
.Vb 2
\&  use Email::Address::XS qw(compose_address);
\&  my $string_address = compose_address($user, $host);
.Ve
.Sp
Takes an unescaped user part and unescaped host part of an address
and returns escaped address.
.Sp
Available since version 1.01.
.IP "split_address" 4
.IX Item "split_address"
.Vb 2
\&  use Email::Address::XS qw(split_address);
\&  my ($user, $host) = split_address($string_address);
.Ve
.Sp
Takes an escaped address and split it into pair of unescaped user
part and unescaped host part of address. If splitting input address
into these two parts is not possible then this function returns
pair of undefs.
.Sp
Available since version 1.01.
.SS "Class Methods"
.IX Subsection "Class Methods"
.IP "new" 4
.IX Item "new"
.Vb 6
\&  my $empty_address = Email::Address::XS\->new();
\&  my $winstons_address = Email::Address::XS\->new(phrase => \*(AqWinston Smith\*(Aq, user => \*(Aqwinston.smith\*(Aq, host => \*(Aqrecdep.minitrue\*(Aq, comment => \*(AqRecords Department\*(Aq);
\&  my $julias_address = Email::Address::XS\->new(\*(AqJulia\*(Aq, \*(Aqjulia@ficdep.minitrue\*(Aq);
\&  my $users_address = Email::Address::XS\->new(address => \*(Aquser@oceania\*(Aq);
\&  my $only_name = Email::Address::XS\->new(phrase => \*(AqName\*(Aq);
\&  my $copy_of_winstons_address = Email::Address::XS\->new(copy => $winstons_address);
.Ve
.Sp
Constructs and returns a new \f(CW\*(C`Email::Address::XS\*(C'\fR object. Takes named
list of arguments: phrase, address, user, host, comment and copy.
An argument address takes precedence over user and host.
.Sp
When an argument copy is specified then it is expected an
Email::Address::XS object and a cloned copy of that object is
returned. All other parameters are ignored.
.Sp
Old syntax from the Email::Address module is
supported too. Takes one to four positional arguments: phrase, address
comment, and original string. Passing an argument original is
deprecated, ignored and throws a warning.
.IP "parse" 4
.IX Item "parse"
.Vb 2
\&  my $winstons_address = Email::Address::XS\->parse(\*(Aq"Winston Smith" <winston.smith@recdep.minitrue> (Records Department)\*(Aq);
\&  my @users_addresses = Email::Address::XS\->parse(\*(Aquser1@oceania, user2@oceania\*(Aq);
.Ve
.Sp
Parses an input string and returns a list of an Email::Address::XS
objects. Same as the function \f(CW\*(C`parse_email_addresses\*(C'\fR
but this one is class method.
.Sp
In scalar context this function returns just first parsed object.
If more then one object was parsed then \f(CW\*(C`is_valid\*(C'\fR
method on returned object returns false. If no object was parsed
then empty Email::Address::XS object is returned.
.Sp
Prior to version 1.01 return value in scalar context is undef when
no object was parsed.
.IP "parse_bare_address" 4
.IX Item "parse_bare_address"
.Vb 1
\&  my $winstons_address = Email::Address::XS\->parse_bare_address(\*(Aqwinston.smith@recdep.minitrue\*(Aq);
.Ve
.Sp
Parses an input string as one bare email address (addr spec) which
does not allow phrase part or angle brackets around email address and
returns an Email::Address::XS object. It is just a wrapper around
\&\f(CW\*(C`address\*(C'\fR method. Method \f(CW\*(C`is_valid\*(C'\fR can be
used to check if parsing was successful.
.Sp
Available since version 1.01.
.SS "Object Methods"
.IX Subsection "Object Methods"
.IP "format" 4
.IX Item "format"
.Vb 1
\&  my $string = $address\->format();
.Ve
.Sp
Returns formatted Email::Address::XS object as a string. This method
throws a warning when \f(CW\*(C`user\*(C'\fR or \f(CW\*(C`host\*(C'\fR part of
the email address is invalid or empty string.
.IP "is_valid" 4
.IX Item "is_valid"
.Vb 1
\&  my $is_valid = $address\->is_valid();
.Ve
.Sp
Returns true if the parse function or method which created this
Email::Address::XS object had not received any syntax error on input
string and also that \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`host\*(C'\fR part of
the email address are not empty strings.
.Sp
Thus this function can be used for checking if Email::Address::XS
object is valid before calling \f(CW\*(C`format\*(C'\fR method on it.
.Sp
Available since version 1.01.
.IP "phrase" 4
.IX Item "phrase"
.Vb 2
\&  my $phrase = $address\->phrase();
\&  $address\->phrase(\*(AqWinston Smith\*(Aq);
.Ve
.Sp
Accessor and mutator for the phrase (display name).
.IP "user" 4
.IX Item "user"
.Vb 2
\&  my $user = $address\->user();
\&  $address\->user(\*(Aqwinston.smith\*(Aq);
.Ve
.Sp
Accessor and mutator for the unescaped user (local/mailbox) part of
an address.
.IP "host" 4
.IX Item "host"
.Vb 2
\&  my $host = $address\->host();
\&  $address\->host(\*(Aqrecdep.minitrue\*(Aq);
.Ve
.Sp
Accessor and mutator for the unescaped host (domain) part of an address.
.Sp
Since version 1.03 this method checks if setting a new value is syntactically
valid. If not undef is set and returned.
.IP "address" 4
.IX Item "address"
.Vb 2
\&  my $string_address = $address\->address();
\&  $address\->address(\*(Aqwinston.smith@recdep.minitrue\*(Aq);
.Ve
.Sp
Accessor and mutator for the escaped address (addr spec).
.Sp
Internally this module stores a user and a host part of an address
separately. Function \f(CW\*(C`compose_address\*(C'\fR is used
for composing full address and function \f(CW\*(C`split_address\*(C'\fR
for splitting into a user and a host parts. If splitting new address
into these two parts is not possible then this method returns undef
and sets both parts to undef.
.IP "comment" 4
.IX Item "comment"
.Vb 2
\&  my $comment = $address\->comment();
\&  $address\->comment(\*(AqRecords Department\*(Aq);
.Ve
.Sp
Accessor and mutator for the comment which is formatted after an
address. A comment can contain another nested comments in round
brackets. When setting new comment this method check if brackets are
balanced. If not undef is set and returned.
.IP "name" 4
.IX Item "name"
.Vb 1
\&  my $name = $address\->name();
.Ve
.Sp
This method tries to return a name which belongs to the address. It
returns either \f(CW\*(C`phrase\*(C'\fR or \f(CW\*(C`comment\*(C'\fR or
\&\f(CW\*(C`user\*(C'\fR part of the address or empty string (first defined
value in this order). But it never returns undef.
.IP "as_string" 4
.IX Item "as_string"
.Vb 2
\&  my $address = Email::Address::XS\->new(phrase => \*(AqWinston Smith\*(Aq, address => \*(Aqwinston.smith@recdep.minitrue\*(Aq);
\&  my $stringified = $address\->as_string();
.Ve
.Sp
This method is used for object stringification. It
returns string representation of object. By default object is
stringified to \f(CW\*(C`format\*(C'\fR.
.Sp
Available since version 1.01.
.IP "original" 4
.IX Item "original"
.Vb 5
\&  my $address = Email::Address::XS\->parse(\*(Aq(Winston) "Smith"   <winston.smith@recdep.minitrue> (Minitrue)\*(Aq);
\&  my $original = $address\->original();
\&  # (Winston) "Smith"   <winston.smith@recdep.minitrue> (Minitrue)
\&  my $format = $address\->format();
\&  # Smith <winston.smith@recdep.minitrue> (Minitrue)
.Ve
.Sp
This method returns original part of the string which was used for
parsing current Email::Address::XS object. If object was not created
by parsing input string, then this method returns undef.
.Sp
Note that \f(CW\*(C`format\*(C'\fR method does not have to return same
original string.
.Sp
Available since version 1.01.
.SS "Overloaded Operators"
.IX Subsection "Overloaded Operators"
.IP "stringify" 4
.IX Item "stringify"
.Vb 3
\&  my $address = Email::Address::XS\->new(phrase => \*(AqWinston Smith\*(Aq, address => \*(Aqwinston.smith@recdep.minitrue\*(Aq);
\&  print "Winston\*(Aqs address is $address.";
\&  # Winston\*(Aqs address is "Winston Smith" <winston.smith@recdep.minitrue>.
.Ve
.Sp
Stringification is done by method \f(CW\*(C`as_string\*(C'\fR.
.SS "Deprecated Functions and Variables"
.IX Subsection "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.
.PP
Altering deprecated variable \f(CW$Email::Address::XS::STRINGIFY\fR changes
method which is called for objects stringification.
.PP
Deprecated cache functions \f(CW\*(C`purge_cache\*(C'\fR, \f(CW\*(C`disable_cache\*(C'\fR and
\&\f(CW\*(C`enable_cache\*(C'\fR are noop and do nothing.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1RFC 822\s0 <https://tools.ietf.org/html/rfc822>,
\&\s-1RFC 2822\s0 <https://tools.ietf.org/html/rfc2822>,
\&\s-1RFC 5322\s0 <https://tools.ietf.org/html/rfc5322>,
Email::MIME::Header::AddressList,
Email::Address,
Email::Address::List,
Email::AddressParser
.SH "AUTHOR"
.IX Header "AUTHOR"
Pali <pali@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2015\-2018 by Pali <pali@cpan.org>
.PP
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.
.PP
Dovecot parser is licensed under The \s-1MIT\s0 License and copyrighted by
Dovecot authors.