1Email::Address(3) User Contributed Perl Documentation Email::Address(3)
2
6 Email::Address - RFC 2822 Address Parsing and Creation
7
9 use Email::Address;
10 my @addresses = Email::Address->parse($line);
12 my $address = Email::Address->new(Casey => 'casey@localhost');
13 print $address->format;
15
17 version 1.886
18 $Id: /my/pep/Email-Address/trunk/lib/Email/Address.pm 31900 2007-06-23T01:25:34.344997Z rjbs $
20
22 This class implements a regex-based RFC 2822 parser that locates email
23 addresses in strings and returns a list of "Email::Address" objects
24 found. Alternatley you may construct objects manually. The goal of
25 this software is to be correct, and very very fast.
26 Package Variables
28 Several regular expressions used in this package are useful to others.
30 For convenience, these variables are declared as package variables that
31 you may access from your program.
32 These regular expressions conform to the rules specified in RFC 2822.
34 You can access these variables using the full namespace. If you want
36 short names, define them yourself.
37 my $addr_spec = $Email::Address::addr_spec;
39 $Email::Address::addr_spec
41 This regular expression defined what an email address is allowed to
42 look like.
43 $Email::Address::angle_addr
45 This regular expression defines an $addr_spec wrapped in angle
46 brackets.
47 $Email::Address::name_addr
49 This regular expression defines what an email address can look like
50 with an optional preceeding display name, also known as the
51 "phrase".
52 $Email::Address::mailbox
54 This is the complete regular expression defining an RFC 2822 emial
55 address with an optional preceeding display name and optional fol‐
56 lowing comment.
57 Class Methods
59 parse
61 my @addrs = Email::Address->parse(
62 q[me@local, Casey <me@local>, "Casey" <me@local> (West)]
63 );
64 This method returns a list of "Email::Address" objects it finds in
66 the input string.
67 The specification for an email address allows for infinitley
69 nestable comments. That's nice in theory, but a little over done.
70 By default this module allows for two (2) levels of nested com‐
71 ments. If you think you need more, modify the $Email::Address::COM‐
72 MENT_NEST_LEVEL package variable to allow more.
73 $Email::Address::COMMENT_NEST_LEVEL = 10; # I'm deep
75 The reason for this hardly limiting limitation is simple: effi‐
77 ciency.
78 Long strings of whitespace can be problematic for this module to
80 parse, a bug which has not yet been adequately addressed. The
81 default behavior is now to collapse multiple spaces into a single
82 space, which avoids this problem. To prevent this behavior, set
83 $Email::Address::COLLAPSE_SPACES to zero. This variable will go
84 away when the bug is resolved properly.
85 new
87 my $address = Email::Address->new(undef, 'casey@local');
88 my $address = Email::Address->new('Casey West', 'casey@local');
89 my $address = Email::Address->new(undef, 'casey@local', '(Casey)');
90 Constructs and returns a new "Email::Address" object. Takes four
92 positional arguments: phrase, email, and comment, and original
93 string.
94 The original string should only really be set using "parse".
96 purge_cache
98 Email::Address->purge_cache;
99 One way this module stays fast is with internal caches. Caches live
101 in memory and there is the remote possibility that you will have a
102 memory problem. In the off chance that you think you're one of
103 those people, this class method will empty those caches.
104 I've loaded over 12000 objects and not encountered a memory prob‐
106 lem.
107 disable_cache
109 enable_cache
110 Email::Address->disable_cache if memory_low();
111 If you'd rather not cache address parses at all, you can disable
113 (and reenable) the Email::Address cache with these methods. The
114 cache is enabled by default.
115 Instance Methods
117 phrase
119 my $phrase = $address->phrase;
120 $address->phrase( "Me oh my" );
121 Accessor and mutator for the phrase portion of an address.
123 address
125 my $addr = $address->address;
126 $addr->address( "me@PROTECTED.com" );
127 Accessor and mutator for the address portion of an address.
129 comment
131 my $comment = $address->comment;
132 $address->comment( "(Work address)" );
133 Accessor and mutator for the comment portion of an address.
135 original
137 my $orig = $address->original;
138 Accessor for the original address found when parsing, or passed to
140 "new".
141 host
143 my $host = $address->host;
144 Accessor for the host portion of an address's address.
146 user
148 my $user = $address->user;
149 Accessor for the user portion of an address's address.
151 format
153 my $printable = $address->format;
154 Returns a properly formatted RFC 2822 address representing the
156 object.
157 name
159 my $name = $address->name;
160 This method tries very hard to determine the name belonging to the
162 address. First the "phrase" is checked. If that doesn't work out
163 the "comment" is looked into. If that still doesn't work out, the
164 "user" portion of the "address" is returned.
165 This method does not try to massage any name it identifies and
167 instead leaves that up to someone else. Who is it to decide if
168 someone wants their name capitalized, or if they're Irish?
169 Overloaded Operators
171 stringify
173 print "I have your email address, $address.";
174 Objects stringify to "format" by default. It's possible that you
176 don't like that idea. Okay, then, you can change it by modifying
177 $Email:Address::STRINGIFY. Please consider modifying this package
178 variable using "local". You might step on someone else's toes if
179 you don't.
180 {
182 local $Email::Address::STRINGIFY = 'address';
183 print "I have your address, $address.";
184 # geeknest.com
185 }
186 print "I have your address, $address.";
187 # "Casey West" <casey@geeknest.com>
188 Did I Mention Fast?
190 On his 1.8GHz Apple MacBook, rjbs gets these results:
192 $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 5
194 Rate Mail::Address Email::Address
195 Mail::Address 2.59/s -- -44%
196 Email::Address 4.59/s 77% --
197 $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 25
199 Rate Mail::Address Email::Address
200 Mail::Address 2.58/s -- -67%
201 Email::Address 7.84/s 204% --
202 $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 50
204 Rate Mail::Address Email::Address
205 Mail::Address 2.57/s -- -70%
206 Email::Address 8.53/s 232% --
207 ...unfortunately, a known bug causes a loss of speed the string to
209 parse has certain known characteristics, and disabling cache will also
210 degrade performance.
211
213 This module is maintained by the Perl Email Project
214 <http://emailproject.perl.org/wiki/Email::Address>
216
218 Email::Simple, perl.
219
221 Originally by Casey West, <casey@geeknest.com>.
222 Maintained, 2006-2007, Ricardo SIGNES <rjbs@cpan.org>.
224
226 Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying
227 phrase-quoting bugs!
228
230 Copyright (c) 2004 Casey West. All rights reserved. This module is
231 free software; you can redistribute it and/or modify it under the same
232 terms as Perl itself.
233perl v5.8.8 2007-06-22 Email::Address(3)