1Email::Address(3) User Contributed Perl Documentation Email::Address(3)
2
6 Email::Address - RFC 2822 Address Parsing and Creation
7
9 version 1.913
10
12 use Email::Address;
13 my @addresses = Email::Address->parse($line);
15 my $address = Email::Address->new(Casey => 'casey@localhost');
16 print $address->format;
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 Version 1.909 and earlier of this module had vulnerabilies
26 (CVE-2015-7686 <https://cve.mitre.org/cgi-
27 bin/cvename.cgi?name=CVE-2015-7686>) and (CVE-2015-12558
28 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-12558>) which
29 allowed specially constructed email to cause a denial of service. The
30 reported vulnerabilities and some other pathalogical cases (meaning
31 they really shouldn't occur in normal email) have been addressed in
32 version 1.910 and newer. If you're running version 1.909 or older, you
33 should update!
34 Alternatively, you could switch to Email::Address::XS which has a
36 backward compatible API. Why not just use that?
37 Package Variables
39 ACHTUNG! Email isn't easy (if even possible) to parse with a regex, at
40 least if you're on a "perl" prior to 5.10.0. Providing regular
41 expressions for use by other programs isn't a great idea, because it
42 makes it hard to improve the parser without breaking the "it's a regex"
43 feature. Using these regular expressions is not encouraged, and
44 methods like "Email::Address->is_addr_spec" should be provided in the
45 future.
46 Several regular expressions used in this package are useful to others.
48 For convenience, these variables are declared as package variables that
49 you may access from your program.
50 These regular expressions conform to the rules specified in RFC 2822.
52 You can access these variables using the full namespace. If you want
54 short names, define them yourself.
55 my $addr_spec = $Email::Address::addr_spec;
57 $Email::Address::addr_spec
59 This regular expression defined what an email address is allowed to
60 look like.
61 $Email::Address::angle_addr
63 This regular expression defines an $addr_spec wrapped in angle
64 brackets.
65 $Email::Address::name_addr
67 This regular expression defines what an email address can look like
68 with an optional preceding display name, also known as the
69 "phrase".
70 $Email::Address::mailbox
72 This is the complete regular expression defining an RFC 2822 email
73 address with an optional preceding display name and optional
74 following comment.
75 Class Methods
77 parse
78 my @addrs = Email::Address->parse(
79 q[me@local, Casey <me@local>, "Casey" <me@local> (West)]
80 );
81 This method returns a list of "Email::Address" objects it finds in
83 the input string. Please note that it returns a list, and expects
84 that it may find multiple addresses. The behavior in scalar
85 context is undefined.
86 The specification for an email address allows for infinitely
88 nestable comments. That's nice in theory, but a little over done.
89 By default this module allows for one (1) level of nested comments.
90 If you think you need more, modify the
91 $Email::Address::COMMENT_NEST_LEVEL package variable to allow more.
92 $Email::Address::COMMENT_NEST_LEVEL = 10; # I'm deep
94 The reason for this hardly-limiting limitation is simple:
96 efficiency.
97 Long strings of whitespace can be problematic for this module to
99 parse, a bug which has not yet been adequately addressed. The
100 default behavior is now to collapse multiple spaces into a single
101 space, which avoids this problem. To prevent this behavior, set
102 $Email::Address::COLLAPSE_SPACES to zero. This variable will go
103 away when the bug is resolved properly.
104 In accordance with RFC 822 and its descendants, this module demands
106 that email addresses be ASCII only. Any non-ASCII content in the
107 parsed addresses will cause the parser to return no results.
108 new
110 my $address = Email::Address->new(undef, 'casey@local');
111 my $address = Email::Address->new('Casey West', 'casey@local');
112 my $address = Email::Address->new(undef, 'casey@local', '(Casey)');
113 Constructs and returns a new "Email::Address" object. Takes four
115 positional arguments: phrase, email, and comment, and original
116 string.
117 The original string should only really be set using "parse".
119 purge_cache
121 Email::Address->purge_cache;
122 One way this module stays fast is with internal caches. Caches live
124 in memory and there is the remote possibility that you will have a
125 memory problem. On the off chance that you think you're one of
126 those people, this class method will empty those caches.
127 I've loaded over 12000 objects and not encountered a memory
129 problem.
130 disable_cache
132 enable_cache
133 Email::Address->disable_cache if memory_low();
134 If you'd rather not cache address parses at all, you can disable
136 (and re-enable) the Email::Address cache with these methods. The
137 cache is enabled by default.
138 Instance Methods
140 phrase
141 my $phrase = $address->phrase;
142 $address->phrase( "Me oh my" );
143 Accessor and mutator for the phrase portion of an address.
145 address
147 my $addr = $address->address;
148 $addr->address( "me@PROTECTED.com" );
149 Accessor and mutator for the address portion of an address.
151 comment
153 my $comment = $address->comment;
154 $address->comment( "(Work address)" );
155 Accessor and mutator for the comment portion of an address.
157 original
159 my $orig = $address->original;
160 Accessor for the original address found when parsing, or passed to
162 "new".
163 host
165 my $host = $address->host;
166 Accessor for the host portion of an address's address.
168 user
170 my $user = $address->user;
171 Accessor for the user portion of an address's address.
173 format
175 my $printable = $address->format;
176 Returns a properly formatted RFC 2822 address representing the
178 object.
179 name
181 my $name = $address->name;
182 This method tries very hard to determine the name belonging to the
184 address. First the "phrase" is checked. If that doesn't work out
185 the "comment" is looked into. If that still doesn't work out, the
186 "user" portion of the "address" is returned.
187 This method does not try to massage any name it identifies and
189 instead leaves that up to someone else. Who is it to decide if
190 someone wants their name capitalized, or if they're Irish?
191 Overloaded Operators
193 stringify
194 print "I have your email address, $address.";
195 Objects stringify to "format" by default. It's possible that you
197 don't like that idea. Okay, then, you can change it by modifying
198 $Email:Address::STRINGIFY. Please consider modifying this package
199 variable using "local". You might step on someone else's toes if
200 you don't.
201 {
203 local $Email::Address::STRINGIFY = 'host';
204 print "I have your address, $address.";
205 # geeknest.com
206 }
207 print "I have your address, $address.";
208 # "Casey West" <casey@geeknest.com>
209 Modifying this package variable is now deprecated. Subclassing is
211 now the recommended approach.
212 Did I Mention Fast?
214 On his 1.8GHz Apple MacBook, rjbs gets these results:
215 $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 5
217 Rate Mail::Address Email::Address
218 Mail::Address 2.59/s -- -44%
219 Email::Address 4.59/s 77% --
220 $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 25
222 Rate Mail::Address Email::Address
223 Mail::Address 2.58/s -- -67%
224 Email::Address 7.84/s 204% --
225 $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 50
227 Rate Mail::Address Email::Address
228 Mail::Address 2.57/s -- -70%
229 Email::Address 8.53/s 232% --
230 ...unfortunately, a known bug causes a loss of speed the string to
232 parse has certain known characteristics, and disabling cache will also
233 degrade performance.
234
236 This library should run on perls released even a long time ago. It
237 should work on any version of perl released in the last five years.
238 Although it may work on older versions of perl, no guarantee is made
240 that the minimum required version will not be increased. The version
241 may be increased for any reason, and there is no promise that patches
242 will be accepted to lower the minimum required perl.
243
245 Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying
246 phrase-quoting bugs!
247
249 • Casey West
250 • Ricardo SIGNES <cpan@semiotic.systems>
252
254 • Alex Vandiver <alex@chmrr.net>
255 • David Golden <dagolden@cpan.org>
257 • David Steinbrunner <dsteinbrunner@pobox.com>
259 • Glenn Fowler <cebjyre@cpan.org>
261 • Jim Brandt <jbrandt@bestpractical.com>
263 • Kevin Falcone <kevin@jibsheet.com>
265 • Pali <pali@cpan.org>
267 • Ricardo Signes <rjbs@semiotic.systems>
269 • Ruslan Zakirov <ruz@bestpractical.com>
271 • sunnavy <sunnavy@bestpractical.com>
273 • William Yardley <pep@veggiechinese.net>
275
277 This software is copyright (c) 2004 by Casey West.
278 This is free software; you can redistribute it and/or modify it under
280 the same terms as the Perl 5 programming language system itself.
281perl v5.36.0 2023-01-20 Email::Address(3)