Email::Address - phpMan

Che Dong
NAME
    Email::Address - RFC 2822 Address Parsing and Creation

VERSION
    version 1.912

SYNOPSIS
      use Email::Address;

      my @addresses = Email::Address->parse($line);
      my $address   = Email::Address->new(Casey => 'casey@localhost');

      print $address->format;

DESCRIPTION
    This class implements a regex-based RFC 2822 parser that locates email
    addresses in strings and returns a list of "Email::Address" objects
    found. Alternatively you may construct objects manually. The goal of
    this software is to be correct, and very very fast.

    Version 1.909 and earlier of this module had vulnerabilies
    (CVE-2015-7686
    <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-7686>) and
    (CVE-2015-12558
    <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-12558>) which
    allowed specially constructed email to cause a denial of service. The
    reported vulnerabilities and some other pathalogical cases (meaning they
    really shouldn't occur in normal email) have been addressed in version
    1.910 and newer. If you're running version 1.909 or older, you should
    update!

    Alternatively, you could switch to Email::Address::XS which has a
    backward compatible API.

  Package Variables
    ACHTUNG! Email isn't easy (if even possible) to parse with a regex, *at
    least* if you're on a "perl" prior to 5.10.0. Providing regular
    expressions for use by other programs isn't a great idea, because it
    makes it hard to improve the parser without breaking the "it's a regex"
    feature. Using these regular expressions is not encouraged, and methods
    like "Email::Address->is_addr_spec" should be provided in the future.

    Several regular expressions used in this package are useful to others.
    For convenience, these variables are declared as package variables that
    you may access from your program.

    These regular expressions conform to the rules specified in RFC 2822.

    You can access these variables using the full namespace. If you want
    short names, define them yourself.

      my $addr_spec = $Email::Address::addr_spec;

    $Email::Address::addr_spec
        This regular expression defined what an email address is allowed to
        look like.

    $Email::Address::angle_addr
        This regular expression defines an $addr_spec wrapped in angle
        brackets.

    $Email::Address::name_addr
        This regular expression defines what an email address can look like
        with an optional preceding display name, also known as the "phrase".

    $Email::Address::mailbox
        This is the complete regular expression defining an RFC 2822 email
        address with an optional preceding display name and optional
        following comment.

  Class Methods
    parse
          my @addrs = Email::Address->parse(
            q[me@local, Casey <me@local>, "Casey" <me@local> (West)]
          );

        This method returns a list of "Email::Address" objects it finds in
        the input string. Please note that it returns a list, and expects
        that it may find multiple addresses. The behavior in scalar context
        is undefined.

        The specification for an email address allows for infinitely
        nestable comments. That's nice in theory, but a little over done. By
        default this module allows for one (1) level of nested comments. If
        you think you need more, modify the
        $Email::Address::COMMENT_NEST_LEVEL package variable to allow more.

          $Email::Address::COMMENT_NEST_LEVEL = 10; # I'm deep

        The reason for this hardly-limiting limitation is simple:
        efficiency.

        Long strings of whitespace can be problematic for this module to
        parse, a bug which has not yet been adequately addressed. The
        default behavior is now to collapse multiple spaces into a single
        space, which avoids this problem. To prevent this behavior, set
        $Email::Address::COLLAPSE_SPACES to zero. This variable will go away
        when the bug is resolved properly.

        In accordance with RFC 822 and its descendants, this module demands
        that email addresses be ASCII only. Any non-ASCII content in the
        parsed addresses will cause the parser to return no results.

    new
          my $address = Email::Address->new(undef, 'casey@local');
          my $address = Email::Address->new('Casey West', 'casey@local');
          my $address = Email::Address->new(undef, 'casey@local', '(Casey)');

        Constructs and returns a new "Email::Address" object. Takes four
        positional arguments: phrase, email, and comment, and original
        string.

        The original string should only really be set using "parse".

    purge_cache
          Email::Address->purge_cache;

        One way this module stays fast is with internal caches. Caches live
        in memory and there is the remote possibility that you will have a
        memory problem. On the off chance that you think you're one of those
        people, this class method will empty those caches.

        I've loaded over 12000 objects and not encountered a memory problem.

    disable_cache
    enable_cache
          Email::Address->disable_cache if memory_low();

        If you'd rather not cache address parses at all, you can disable
        (and re-enable) the Email::Address cache with these methods. The
        cache is enabled by default.

  Instance Methods
    phrase
          my $phrase = $address->phrase;
          $address->phrase( "Me oh my" );

        Accessor and mutator for the phrase portion of an address.

    address
          my $addr = $address->address;
          $addr->address( "me AT PROTECTED.com" );

        Accessor and mutator for the address portion of an address.

    comment
          my $comment = $address->comment;
          $address->comment( "(Work address)" );

        Accessor and mutator for the comment portion of an address.

    original
          my $orig = $address->original;

        Accessor for the original address found when parsing, or passed to
        "new".

    host
          my $host = $address->host;

        Accessor for the host portion of an address's address.

    user
          my $user = $address->user;

        Accessor for the user portion of an address's address.

    format
          my $printable = $address->format;

        Returns a properly formatted RFC 2822 address representing the
        object.

    name
          my $name = $address->name;

        This method tries very hard to determine the name belonging to the
        address. First the "phrase" is checked. If that doesn't work out the
        "comment" is looked into. If that still doesn't work out, the "user"
        portion of the "address" is returned.

        This method does not try to massage any name it identifies and
        instead leaves that up to someone else. Who is it to decide if
        someone wants their name capitalized, or if they're Irish?

  Overloaded Operators
    stringify
          print "I have your email address, $address.";

        Objects stringify to "format" by default. It's possible that you
        don't like that idea. Okay, then, you can change it by modifying
        $Email:Address::STRINGIFY. Please consider modifying this package
        variable using "local". You might step on someone else's toes if you
        don't.

          {
            local $Email::Address::STRINGIFY = 'host';
            print "I have your address, $address.";
            #   geeknest.com
          }
          print "I have your address, $address.";
          #   "Casey West" <casey AT geeknest.com>

        Modifying this package variable is now deprecated. Subclassing is
        now the recommended approach.

  Did I Mention Fast?
    On his 1.8GHz Apple MacBook, rjbs gets these results:

      $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 5
                       Rate  Mail::Address Email::Address
      Mail::Address  2.59/s             --           -44%
      Email::Address 4.59/s            77%             --

      $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 25
                       Rate  Mail::Address Email::Address
      Mail::Address  2.58/s             --           -67%
      Email::Address 7.84/s           204%             --

      $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 50
                       Rate  Mail::Address Email::Address
      Mail::Address  2.57/s             --           -70%
      Email::Address 8.53/s           232%             --

    ...unfortunately, a known bug causes a loss of speed the string to parse
    has certain known characteristics, and disabling cache will also degrade
    performance.

ACKNOWLEDGEMENTS
    Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying
    phrase-quoting bugs!

AUTHORS
    *   Casey West

    *   Ricardo SIGNES <rjbs AT cpan.org>

CONTRIBUTORS
    *   Alex Vandiver <alex AT chmrr.net>

    *   David Golden <dagolden AT cpan.org>

    *   David Steinbrunner <dsteinbrunner AT pobox.com>

    *   Glenn Fowler <cebjyre AT cpan.org>

    *   Jim Brandt <jbrandt AT bestpractical.com>

    *   Kevin Falcone <kevin AT jibsheet.com>

    *   Pali <pali AT cpan.org>

    *   Ruslan Zakirov <ruz AT bestpractical.com>

    *   sunnavy <sunnavy AT bestpractical.com>

    *   William Yardley <pep AT veggiechinese.net>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2004 by 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.