# Email::Address::XS - Parse and format RFC 5322 email addresses and groups - perldoc - [phpMan]

## NAME
    [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) - Parse and format RFC 5322 email addresses and groups

## SYNOPSIS
      use [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown);

      my $winstons_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->new('Julia', '<julia@ficdep.minitrue>');
      print $julias_address->format();
      # Julia <<julia@ficdep.minitrue>>

      my $users_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->parse('user <user@oceania>');
      print $users_address->host();
      # oceania

      my $goldsteins_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->parse_bare_address('<goldstein@brotherhood.oceania>');
      print $goldsteins_address->user();
      # goldstein

      my @addresses = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->parse('"Winston Smith" <<winston.smith@recdep.minitrue>> (Records Department), Julia <<julia@ficdep.minitrue>>');
      # ($winstons_address, $julias_address)


      use [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) 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
    This module implements RFC 5322 <<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 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 Dovecot IMAP
    server.

    It is a drop-in replacement for the [Email::Address](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress/markdown) version 1.908.

    [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) module was created to finally fix CVE-2015-7686.

    Existing applications that use [Email::Address](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress/markdown) module could be easily switched to
    [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) module. In most cases only changing "use [Email::Address](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress/markdown)" to "use
    [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)" and replacing every "[Email::Address](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress/markdown)" occurrence with "[Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)" is
    sufficient.

    So unlike [Email::Address](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress/markdown), this module does not use regular expressions for parsing but instead
    native XS implementation parses input string sequentially according to RFC 5322 grammar.

    Additionally it has support also for named groups and so can be use instead of the
    [Email::Address::List](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AList/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AMIME%3A%3AHeader%3A%3AAddressList/markdown).

  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](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) qw(format_email_addresses);

          my $winstons_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->new(phrase => 'Winston Smith', address => '<winston@recdep.minitrue>');
          my $julias_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->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.

    format_email_groups
          use [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) qw(format_email_groups);

          my $winstons_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->new(phrase => 'Winston Smith', user => 'winston.smith', host => 'recdep.minitrue');
          my $julias_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->new('Julia', '<julia@ficdep.minitrue>');
          my $users_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->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 address list. If a group is not undef then address list is formatted
        inside named group.

    parse_email_addresses
          use [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) objects, one for each address

        Parses an input string and returns a list of [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) objects. Optional second
        string argument specifies class name for blessing new objects.

    parse_email_groups
          use [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) 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 a same format as a input for the function "format_email_groups". This function preserves
        order of groups and does not do any de-duplication or merging.

    compose_address
          use [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) qw(compose_address);
          my $string_address = compose_address($user, $host);

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

        Available since version 1.01.

    split_address
          use [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) qw(split_address);
          my ($user, $host) = split_address($string_address);

        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.

        Available since version 1.01.

### Class Methods
    new
          my $empty_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->new();
          my $winstons_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->new(phrase => 'Winston Smith', user => 'winston.smith', host => 'recdep.minitrue', comment => 'Records Department');
          my $julias_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->new('Julia', '<julia@ficdep.minitrue>');
          my $users_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->new(address => 'user@oceania');
          my $only_name = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->new(phrase => 'Name');
          my $copy_of_winstons_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->new(copy => $winstons_address);

        Constructs and returns a new "[Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)" object. Takes 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 an [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) object and a
        cloned copy of that object is returned. All other parameters are ignored.

        Old syntax from the [Email::Address](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress/markdown) 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.

    parse
          my $winstons_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->parse('"Winston Smith" <<winston.smith@recdep.minitrue>> (Records Department)');
          my @users_addresses = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->parse('user1@oceania, user2@oceania');

        Parses an input string and returns a list of an [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) objects. Same as the
        function "parse_email_addresses" but this one is class method.

        In scalar context this function returns just first parsed object. If more then one object
        was parsed then "is_valid" method on returned object returns false. If no object was parsed
        then empty [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) object is returned.

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

    parse_bare_address
          my $winstons_address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->parse_bare_address('<winston.smith@recdep.minitrue>');

        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](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) object. It is
        just a wrapper around "address" method. Method "is_valid" can be used to check if parsing
        was successful.

        Available since version 1.01.

### Object Methods
    format
          my $string = $address->format();

        Returns formatted [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) object as a string. This method throws a warning when
        "user" or "host" part of the email address is invalid or empty string.

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

        Returns true if the parse function or method which created this [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) object
        had not received any syntax error on input string and also that "user" and "host" part of
        the email address are not empty strings.

        Thus this function can be used for checking if [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) object is valid before
        calling "format" method on it.

        Available since version 1.01.

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

        Accessor and mutator for the phrase (display name).

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

        Accessor and mutator for the unescaped user (local/mailbox) part of an address.

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

        Accessor and mutator for the unescaped host (domain) part of an address.

        Since version 1.03 this method checks if setting a new value is syntactically valid. If not
        undef is set and returned.

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

        Accessor and mutator for the escaped address (addr spec).

        Internally this module stores a user and a host part of an address separately. Function
        "compose_address" is used for composing full address and function "split_address" 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.

    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 new comment this method
        check if brackets are balanced. If not undef is set and returned.

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

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

    as_string
          my $address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->new(phrase => 'Winston Smith', address => '<winston.smith@recdep.minitrue>');
          my $stringified = $address->as_string();

        This method is used for object stringification. It returns string representation of object.
        By default object is stringified to "format".

        Available since version 1.01.

    original
          my $address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->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 original part of the string which was used for parsing current
        [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown) object. If object was not created by parsing input string, then this
        method returns undef.

        Note that "format" method does not have to return same original string.

        Available since version 1.01.

### Overloaded Operators
    stringify
          my $address = [Email::Address::XS](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/markdown)->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".

### Deprecated Functions and Variables
    For compatibility with the [Email::Address](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress/markdown) module there are defined some deprecated functions and
    variables. Do not use them in new code. Their usage throws warnings.

    Altering deprecated variable $[Email::Address::XS::STRINGIFY](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS%3A%3ASTRINGIFY/markdown) changes method which is called for
    objects stringification.

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

## SEE ALSO
    RFC 822 <<https://tools.ietf.org/html/rfc822>>, RFC 2822 <<https://tools.ietf.org/html/rfc2822>>,
    RFC 5322 <<https://tools.ietf.org/html/rfc5322>>, [Email::MIME::Header::AddressList](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AMIME%3A%3AHeader%3A%3AAddressList/markdown),
    [Email::Address](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress/markdown), [Email::Address::List](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AList/markdown), [Email::AddressParser](https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddressParser/markdown)

## AUTHOR
    Pali <<pali@cpan.org>>

## COPYRIGHT AND LICENSE
    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.

    Dovecot parser is licensed under The MIT License and copyrighted by Dovecot authors.