1Email::Address(3)     User Contributed Perl Documentation    Email::Address(3)
2
3
4

NAME

6       Email::Address - RFC 2822 Address Parsing and Creation
7

VERSION

9       version 1.912
10

SYNOPSIS

12         use Email::Address;
13
14         my @addresses = Email::Address->parse($line);
15         my $address   = Email::Address->new(Casey => 'casey@localhost');
16
17         print $address->format;
18

DESCRIPTION

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
25       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
35       Alternatively, you could switch to Email::Address::XS which has a
36       backward compatible API.
37
38   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
47       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
51       These regular expressions conform to the rules specified in RFC 2822.
52
53       You can access these variables using the full namespace. If you want
54       short names, define them yourself.
55
56         my $addr_spec = $Email::Address::addr_spec;
57
58       $Email::Address::addr_spec
59           This regular expression defined what an email address is allowed to
60           look like.
61
62       $Email::Address::angle_addr
63           This regular expression defines an $addr_spec wrapped in angle
64           brackets.
65
66       $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
71       $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
76   Class Methods
77       parse
78             my @addrs = Email::Address->parse(
79               q[me@local, Casey <me@local>, "Casey" <me@local> (West)]
80             );
81
82           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
87           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
93             $Email::Address::COMMENT_NEST_LEVEL = 10; # I'm deep
94
95           The reason for this hardly-limiting limitation is simple:
96           efficiency.
97
98           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
105           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
109       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
114           Constructs and returns a new "Email::Address" object. Takes four
115           positional arguments: phrase, email, and comment, and original
116           string.
117
118           The original string should only really be set using "parse".
119
120       purge_cache
121             Email::Address->purge_cache;
122
123           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
128           I've loaded over 12000 objects and not encountered a memory
129           problem.
130
131       disable_cache
132       enable_cache
133             Email::Address->disable_cache if memory_low();
134
135           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
139   Instance Methods
140       phrase
141             my $phrase = $address->phrase;
142             $address->phrase( "Me oh my" );
143
144           Accessor and mutator for the phrase portion of an address.
145
146       address
147             my $addr = $address->address;
148             $addr->address( "me@PROTECTED.com" );
149
150           Accessor and mutator for the address portion of an address.
151
152       comment
153             my $comment = $address->comment;
154             $address->comment( "(Work address)" );
155
156           Accessor and mutator for the comment portion of an address.
157
158       original
159             my $orig = $address->original;
160
161           Accessor for the original address found when parsing, or passed to
162           "new".
163
164       host
165             my $host = $address->host;
166
167           Accessor for the host portion of an address's address.
168
169       user
170             my $user = $address->user;
171
172           Accessor for the user portion of an address's address.
173
174       format
175             my $printable = $address->format;
176
177           Returns a properly formatted RFC 2822 address representing the
178           object.
179
180       name
181             my $name = $address->name;
182
183           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
188           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
192   Overloaded Operators
193       stringify
194             print "I have your email address, $address.";
195
196           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
202             {
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
210           Modifying this package variable is now deprecated. Subclassing is
211           now the recommended approach.
212
213   Did I Mention Fast?
214       On his 1.8GHz Apple MacBook, rjbs gets these results:
215
216         $ 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
221         $ 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
226         $ 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
231       ...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

ACKNOWLEDGEMENTS

236       Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying
237       phrase-quoting bugs!
238

AUTHORS

240       •   Casey West
241
242       •   Ricardo SIGNES <rjbs@cpan.org>
243

CONTRIBUTORS

245       •   Alex Vandiver <alex@chmrr.net>
246
247       •   David Golden <dagolden@cpan.org>
248
249       •   David Steinbrunner <dsteinbrunner@pobox.com>
250
251       •   Glenn Fowler <cebjyre@cpan.org>
252
253       •   Jim Brandt <jbrandt@bestpractical.com>
254
255       •   Kevin Falcone <kevin@jibsheet.com>
256
257       •   Pali <pali@cpan.org>
258
259       •   Ruslan Zakirov <ruz@bestpractical.com>
260
261       •   sunnavy <sunnavy@bestpractical.com>
262
263       •   William Yardley <pep@veggiechinese.net>
264
266       This software is copyright (c) 2004 by Casey West.
267
268       This is free software; you can redistribute it and/or modify it under
269       the same terms as the Perl 5 programming language system itself.
270
271
272
273perl v5.34.0                      2022-01-21                 Email::Address(3)
Impressum