| Email::Address - RFC 2822 Address Parsing and Creation |
Email::Address - RFC 2822 Address Parsing and Creation
use Email::Address;
my @addresses = Email::Address->parse($line); my $address = Email::Address->new(Casey => 'casey@localhost');
print $address->format;
version 1.886
$Id: Address.pm 881 2007-12-19 22:08:35Z rjbs@cpan.org $
This class implements a regex-based RFC 2822 parser that locates email
addresses in strings and returns a list of Email::Address objects found.
Alternatley you may construct objects manually. The goal of this software is to
be correct, and very very fast.
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;
$addr_spec wrapped in angle
brackets.
phrase.
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.
The specification for an email address allows for infinitley
nestable comments. That's nice in theory, but a little over done.
By default this module allows for two (2) levels 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.
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.
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. In 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.
Email::Address->disable_cache if memory_low();
If you'd rather not cache address parses at all, you can disable (and reenable) the Email::Address cache with these methods. The cache is enabled by default.
my $phrase = $address->phrase; $address->phrase( "Me oh my" );
Accessor and mutator for the phrase portion of an address.
my $addr = $address->address; $addr->address( "me@PROTECTED.com" );
Accessor and mutator for the address portion of an address.
my $comment = $address->comment; $address->comment( "(Work address)" );
Accessor and mutator for the comment portion of an address.
my $orig = $address->original;
Accessor for the original address found when parsing, or passed
to new.
my $host = $address->host;
Accessor for the host portion of an address's address.
my $user = $address->user;
Accessor for the user portion of an address's address.
my $printable = $address->format;
Returns a properly formatted RFC 2822 address representing the object.
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?
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 = 'address';
print "I have your address, $address.";
# geeknest.com
}
print "I have your address, $address.";
# "Casey West" <casey@geeknest.com>
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.
This module is maintained by the Perl Email Project
http://emailproject.perl.org/wiki/Email::Address
the Email::Simple manpage, the perl manpage.
Originally by Casey West, <casey@geeknest.com>.
Maintained, 2006-2007, Ricardo SIGNES <rjbs@cpan.org>.
Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying phrase-quoting bugs!
Copyright (c) 2004 Casey West. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
| Email::Address - RFC 2822 Address Parsing and Creation |