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.898
18
20 This class implements a regex-based RFC 2822 parser that locates email
21 addresses in strings and returns a list of "Email::Address" objects
22 found. Alternatively you may construct objects manually. The goal of
23 this software is to be correct, and very very fast.
24 Package Variables
26 ACHTUNG! Email isn't easy (if even possible) to parse with a regex, at
27 least if you're on a "perl" prior to 5.10.0. Providing regular
28 expressions for use by other programs isn't a great idea, because it
29 makes it hard to improve the parser without breaking the "it's a regex"
30 feature. Using these regular expressions is not encouraged, and
31 methods like "Email::Address->is_addr_spec" should be provided in the
32 future.
33 Several regular expressions used in this package are useful to others.
35 For convenience, these variables are declared as package variables that
36 you may access from your program.
37 These regular expressions conform to the rules specified in RFC 2822.
39 You can access these variables using the full namespace. If you want
41 short names, define them yourself.
42 my $addr_spec = $Email::Address::addr_spec;
44 $Email::Address::addr_spec
46 This regular expression defined what an email address is allowed to
47 look like.
48 $Email::Address::angle_addr
50 This regular expression defines an $addr_spec wrapped in angle
51 brackets.
52 $Email::Address::name_addr
54 This regular expression defines what an email address can look like
55 with an optional preceding display name, also known as the
56 "phrase".
57 $Email::Address::mailbox
59 This is the complete regular expression defining an RFC 2822 emial
60 address with an optional preceding display name and optional
61 following comment.
62 Class Methods
64 parse
65 my @addrs = Email::Address->parse(
66 q[me@local, Casey <me@local>, "Casey" <me@local> (West)]
67 );
68 This method returns a list of "Email::Address" objects it finds in
70 the input string.
71 The specification for an email address allows for infinitley
73 nestable comments. That's nice in theory, but a little over done.
74 By default this module allows for two (2) levels of nested
75 comments. If you think you need more, modify the
76 $Email::Address::COMMENT_NEST_LEVEL package variable to allow more.
77 $Email::Address::COMMENT_NEST_LEVEL = 10; # I'm deep
79 The reason for this hardly-limiting limitation is simple:
81 efficiency.
82 Long strings of whitespace can be problematic for this module to
84 parse, a bug which has not yet been adequately addressed. The
85 default behavior is now to collapse multiple spaces into a single
86 space, which avoids this problem. To prevent this behavior, set
87 $Email::Address::COLLAPSE_SPACES to zero. This variable will go
88 away when the bug is resolved properly.
89 In accordance with RFC 822 and its descendants, this module demands
91 that email addresses be ASCII only. Any non-ASCII content in the
92 parsed addresses will cause the parser to return no results.
93 new
95 my $address = Email::Address->new(undef, 'casey@local');
96 my $address = Email::Address->new('Casey West', 'casey@local');
97 my $address = Email::Address->new(undef, 'casey@local', '(Casey)');
98 Constructs and returns a new "Email::Address" object. Takes four
100 positional arguments: phrase, email, and comment, and original
101 string.
102 The original string should only really be set using "parse".
104 purge_cache
106 Email::Address->purge_cache;
107 One way this module stays fast is with internal caches. Caches live
109 in memory and there is the remote possibility that you will have a
110 memory problem. On the off chance that you think you're one of
111 those people, this class method will empty those caches.
112 I've loaded over 12000 objects and not encountered a memory
114 problem.
115 disable_cache
117 enable_cache
118 Email::Address->disable_cache if memory_low();
119 If you'd rather not cache address parses at all, you can disable
121 (and re-enable) the Email::Address cache with these methods. The
122 cache is enabled by default.
123 Instance Methods
125 phrase
126 my $phrase = $address->phrase;
127 $address->phrase( "Me oh my" );
128 Accessor and mutator for the phrase portion of an address.
130 address
132 my $addr = $address->address;
133 $addr->address( "me@PROTECTED.com" );
134 Accessor and mutator for the address portion of an address.
136 comment
138 my $comment = $address->comment;
139 $address->comment( "(Work address)" );
140 Accessor and mutator for the comment portion of an address.
142 original
144 my $orig = $address->original;
145 Accessor for the original address found when parsing, or passed to
147 "new".
148 host
150 my $host = $address->host;
151 Accessor for the host portion of an address's address.
153 user
155 my $user = $address->user;
156 Accessor for the user portion of an address's address.
158 format
160 my $printable = $address->format;
161 Returns a properly formatted RFC 2822 address representing the
163 object.
164 name
166 my $name = $address->name;
167 This method tries very hard to determine the name belonging to the
169 address. First the "phrase" is checked. If that doesn't work out
170 the "comment" is looked into. If that still doesn't work out, the
171 "user" portion of the "address" is returned.
172 This method does not try to massage any name it identifies and
174 instead leaves that up to someone else. Who is it to decide if
175 someone wants their name capitalized, or if they're Irish?
176 Overloaded Operators
178 stringify
179 print "I have your email address, $address.";
180 Objects stringify to "format" by default. It's possible that you
182 don't like that idea. Okay, then, you can change it by modifying
183 $Email:Address::STRINGIFY. Please consider modifying this package
184 variable using "local". You might step on someone else's toes if
185 you don't.
186 {
188 local $Email::Address::STRINGIFY = 'host';
189 print "I have your address, $address.";
190 # geeknest.com
191 }
192 print "I have your address, $address.";
193 # "Casey West" <casey@geeknest.com>
194 Modifying this package variable is now deprecated. Subclassing is
196 now the recommended approach.
197 Did I Mention Fast?
199 On his 1.8GHz Apple MacBook, rjbs gets these results:
200 $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 5
202 Rate Mail::Address Email::Address
203 Mail::Address 2.59/s -- -44%
204 Email::Address 4.59/s 77% --
205 $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 25
207 Rate Mail::Address Email::Address
208 Mail::Address 2.58/s -- -67%
209 Email::Address 7.84/s 204% --
210 $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 50
212 Rate Mail::Address Email::Address
213 Mail::Address 2.57/s -- -70%
214 Email::Address 8.53/s 232% --
215 ...unfortunately, a known bug causes a loss of speed the string to
217 parse has certain known characteristics, and disabling cache will also
218 degrade performance.
219
221 Email::Simple, perl.
222
224 Originally by Casey West, <casey@geeknest.com>.
225 Maintained, 2006-2007, Ricardo SIGNES <rjbs@cpan.org>.
227
229 Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying
230 phrase-quoting bugs!
231
233 Copyright (c) 2004 Casey West. All rights reserved. This module is
234 free software; you can redistribute it and/or modify it under the same
235 terms as Perl itself.
236perl v5.16.3 2013-02-07 Email::Address(3)