Email::Address(3) User Contributed Perl Documentation Email::Address(3)NAMEEmail::Address - RFC 2822 Address Parsing and Creation
SYNOPSIS
use Email::Address;
my @addresses = Email::Address->parse($line);
my $address = Email::Address->new(Casey => 'casey@localhost');
print $address->format;
VERSION
version 1.886
$Id: Address.pm 881 2007-12-19 22:08:35Z rjbs@cpan.org $
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. Alternatley you may construct objects manually. The goal of
this software is to be correct, and very very fast.
Package Variables
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 preceeding display name, also known as the
"phrase".
$Email::Address::mailbox
This is the complete regular expression defining an RFC 2822 emial
address with an optional preceeding 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.
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.
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. 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.
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 reenable) 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@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 = 'address';
print "I have your address, $address.";
# geeknest.com
}
print "I have your address, $address.";
# "Casey West" <casey@geeknest.com>
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.
PERL EMAIL PROJECT
This module is maintained by the Perl Email Project
<http://emailproject.perl.org/wiki/Email::Address>
SEE ALSO
Email::Simple, perl.
AUTHOR
Originally by Casey West, <casey@geeknest.com>.
Maintained, 2006-2007, Ricardo SIGNES <rjbs@cpan.org>.
ACKNOWLEDGEMENTS
Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying
phrase-quoting bugs!
COPYRIGHT
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.
perl v5.14.1 2007-12-19 Email::Address(3)
