line |
stmt |
bran |
cond |
sub |
pod |
time |
code |
1
|
10
|
|
|
10
|
|
406483
|
use strict; |
|
10
|
|
|
|
|
78
|
|
|
10
|
|
|
|
|
301
|
|
2
|
10
|
|
|
10
|
|
53
|
use warnings; |
|
10
|
|
|
|
|
17
|
|
|
10
|
|
|
|
|
11493
|
|
3
|
|
|
|
|
|
|
package Email::Address; |
4
|
|
|
|
|
|
|
# ABSTRACT: RFC 2822 Address Parsing and Creation |
5
|
|
|
|
|
|
|
$Email::Address::VERSION = '1.912'; |
6
|
|
|
|
|
|
|
our $COMMENT_NEST_LEVEL ||= 1; |
7
|
|
|
|
|
|
|
our $STRINGIFY ||= 'format'; |
8
|
|
|
|
|
|
|
our $COLLAPSE_SPACES = 1 unless defined $COLLAPSE_SPACES; # I miss //= |
9
|
|
|
|
|
|
|
|
10
|
|
|
|
|
|
|
#pod =head1 SYNOPSIS |
11
|
|
|
|
|
|
|
#pod |
12
|
|
|
|
|
|
|
#pod use Email::Address; |
13
|
|
|
|
|
|
|
#pod |
14
|
|
|
|
|
|
|
#pod my @addresses = Email::Address->parse($line); |
15
|
|
|
|
|
|
|
#pod my $address = Email::Address->new(Casey => 'casey@localhost'); |
16
|
|
|
|
|
|
|
#pod |
17
|
|
|
|
|
|
|
#pod print $address->format; |
18
|
|
|
|
|
|
|
#pod |
19
|
|
|
|
|
|
|
#pod =head1 DESCRIPTION |
20
|
|
|
|
|
|
|
#pod |
21
|
|
|
|
|
|
|
#pod This class implements a regex-based RFC 2822 parser that locates email |
22
|
|
|
|
|
|
|
#pod addresses in strings and returns a list of C objects found. |
23
|
|
|
|
|
|
|
#pod Alternatively you may construct objects manually. The goal of this software is |
24
|
|
|
|
|
|
|
#pod to be correct, and very very fast. |
25
|
|
|
|
|
|
|
#pod |
26
|
|
|
|
|
|
|
#pod Version 1.909 and earlier of this module had vulnerabilies |
27
|
|
|
|
|
|
|
#pod (L) |
28
|
|
|
|
|
|
|
#pod and (L) |
29
|
|
|
|
|
|
|
#pod which allowed specially constructed email to cause a denial of service. The |
30
|
|
|
|
|
|
|
#pod reported vulnerabilities and some other pathalogical cases (meaning they really |
31
|
|
|
|
|
|
|
#pod shouldn't occur in normal email) have been addressed in version 1.910 and newer. |
32
|
|
|
|
|
|
|
#pod If you're running version 1.909 or older, you should update! |
33
|
|
|
|
|
|
|
#pod |
34
|
|
|
|
|
|
|
#pod Alternatively, you could switch to L|Email::Address::XS> |
35
|
|
|
|
|
|
|
#pod which has a backward compatible API. |
36
|
|
|
|
|
|
|
#pod |
37
|
|
|
|
|
|
|
#pod =cut |
38
|
|
|
|
|
|
|
|
39
|
|
|
|
|
|
|
my $CTL = q{\x00-\x1F\x7F}; |
40
|
|
|
|
|
|
|
my $special = q{()<>\\[\\]:;@\\\\,."}; |
41
|
|
|
|
|
|
|
|
42
|
|
|
|
|
|
|
my $text = qr/[^\x0A\x0D]/; |
43
|
|
|
|
|
|
|
|
44
|
|
|
|
|
|
|
my $quoted_pair = qr/\\$text/; |
45
|
|
|
|
|
|
|
|
46
|
|
|
|
|
|
|
my $ctext = qr/(?>[^()\\]+)/; |
47
|
|
|
|
|
|
|
my ($ccontent, $comment) = (q{})x2; |
48
|
|
|
|
|
|
|
for (1 .. $COMMENT_NEST_LEVEL) { |
49
|
|
|
|
|
|
|
$ccontent = qr/$ctext|$quoted_pair|$comment/; |
50
|
|
|
|
|
|
|
$comment = qr/(?>\s*\((?:\s*$ccontent)*\s*\)\s*)/; |
51
|
|
|
|
|
|
|
} |
52
|
|
|
|
|
|
|
my $cfws = qr/$comment|(?>\s+)/; |
53
|
|
|
|
|
|
|
|
54
|
|
|
|
|
|
|
my $atext = qq/[^$CTL$special\\s]/; |
55
|
|
|
|
|
|
|
my $atom = qr/(?>$cfws*$atext+$cfws*)/; |
56
|
|
|
|
|
|
|
my $dot_atom_text = qr/(?>$atext+(?:\.$atext+)*)/; |
57
|
|
|
|
|
|
|
my $dot_atom = qr/(?>$cfws*$dot_atom_text$cfws*)/; |
58
|
|
|
|
|
|
|
|
59
|
|
|
|
|
|
|
my $qtext = qr/[^\\"]/; |
60
|
|
|
|
|
|
|
my $qcontent = qr/$qtext|$quoted_pair/; |
61
|
|
|
|
|
|
|
my $quoted_string = qr/(?>$cfws*"$qcontent*"$cfws*)/; |
62
|
|
|
|
|
|
|
|
63
|
|
|
|
|
|
|
my $word = qr/$atom|$quoted_string/; |
64
|
|
|
|
|
|
|
|
65
|
|
|
|
|
|
|
# XXX: This ($phrase) used to just be: my $phrase = qr/$word+/; It was changed |
66
|
|
|
|
|
|
|
# to resolve bug 22991, creating a significant slowdown. Given current speed |
67
|
|
|
|
|
|
|
# problems. Once 16320 is resolved, this section should be dealt with. |
68
|
|
|
|
|
|
|
# -- rjbs, 2006-11-11 |
69
|
|
|
|
|
|
|
#my $obs_phrase = qr/$word(?:$word|\.|$cfws)*/; |
70
|
|
|
|
|
|
|
|
71
|
|
|
|
|
|
|
# XXX: ...and the above solution caused endless problems (never returned) when |
72
|
|
|
|
|
|
|
# examining this address, now in a test: |
73
|
|
|
|
|
|
|
# admin+=E6=96=B0=E5=8A=A0=E5=9D=A1_Weblog-- ATAT --test.socialtext.com |
74
|
|
|
|
|
|
|
# So we disallow the hateful CFWS in this context for now. Of modern mail |
75
|
|
|
|
|
|
|
# agents, only Apple Web Mail 2.0 is known to produce obs-phrase. |
76
|
|
|
|
|
|
|
# -- rjbs, 2006-11-19 |
77
|
|
|
|
|
|
|
my $simple_word = qr/(?>$atom|\.|\s*"$qcontent+"\s*)/; |
78
|
|
|
|
|
|
|
my $obs_phrase = qr/(?>$simple_word+)/; |
79
|
|
|
|
|
|
|
|
80
|
|
|
|
|
|
|
my $phrase = qr/$obs_phrase|(?>$word+)/; |
81
|
|
|
|
|
|
|
|
82
|
|
|
|
|
|
|
my $local_part = qr/$dot_atom|$quoted_string/; |
83
|
|
|
|
|
|
|
my $dtext = qr/[^\[\]\\]/; |
84
|
|
|
|
|
|
|
my $dcontent = qr/$dtext|$quoted_pair/; |
85
|
|
|
|
|
|
|
my $domain_literal = qr/(?>$cfws*\[(?:\s*$dcontent)*\s*\]$cfws*)/; |
86
|
|
|
|
|
|
|
my $domain = qr/$dot_atom|$domain_literal/; |
87
|
|
|
|
|
|
|
|
88
|
|
|
|
|
|
|
my $display_name = $phrase; |
89
|
|
|
|
|
|
|
|
90
|
|
|
|
|
|
|
#pod =head2 Package Variables |
91
|
|
|
|
|
|
|
#pod |
92
|
|
|
|
|
|
|
#pod B Email isn't easy (if even possible) to parse with a regex, I
|
93
|
|
|
|
|
|
|
#pod least> if you're on a C prior to 5.10.0. Providing regular expressions |
94
|
|
|
|
|
|
|
#pod for use by other programs isn't a great idea, because it makes it hard to |
95
|
|
|
|
|
|
|
#pod improve the parser without breaking the "it's a regex" feature. Using these |
96
|
|
|
|
|
|
|
#pod regular expressions is not encouraged, and methods like C<< |
97
|
|
|
|
|
|
|
#pod Email::Address->is_addr_spec >> should be provided in the future. |
98
|
|
|
|
|
|
|
#pod |
99
|
|
|
|
|
|
|
#pod Several regular expressions used in this package are useful to others. |
100
|
|
|
|
|
|
|
#pod For convenience, these variables are declared as package variables that |
101
|
|
|
|
|
|
|
#pod you may access from your program. |
102
|
|
|
|
|
|
|
#pod |
103
|
|
|
|
|
|
|
#pod These regular expressions conform to the rules specified in RFC 2822. |
104
|
|
|
|
|
|
|
#pod |
105
|
|
|
|
|
|
|
#pod You can access these variables using the full namespace. If you want |
106
|
|
|
|
|
|
|
#pod short names, define them yourself. |
107
|
|
|
|
|
|
|
#pod |
108
|
|
|
|
|
|
|
#pod my $addr_spec = $Email::Address::addr_spec; |
109
|
|
|
|
|
|
|
#pod |
110
|
|
|
|
|
|
|
#pod =over 4 |
111
|
|
|
|
|
|
|
#pod |
112
|
|
|
|
|
|
|
#pod =item $Email::Address::addr_spec |
113
|
|
|
|
|
|
|
#pod |
114
|
|
|
|
|
|
|
#pod This regular expression defined what an email address is allowed to |
115
|
|
|
|
|
|
|
#pod look like. |
116
|
|
|
|
|
|
|
#pod |
117
|
|
|
|
|
|
|
#pod =item $Email::Address::angle_addr |
118
|
|
|
|
|
|
|
#pod |
119
|
|
|
|
|
|
|
#pod This regular expression defines an C<$addr_spec> wrapped in angle |
120
|
|
|
|
|
|
|
#pod brackets. |
121
|
|
|
|
|
|
|
#pod |
122
|
|
|
|
|
|
|
#pod =item $Email::Address::name_addr |
123
|
|
|
|
|
|
|
#pod |
124
|
|
|
|
|
|
|
#pod This regular expression defines what an email address can look like |
125
|
|
|
|
|
|
|
#pod with an optional preceding display name, also known as the C. |
126
|
|
|
|
|
|
|
#pod |
127
|
|
|
|
|
|
|
#pod =item $Email::Address::mailbox |
128
|
|
|
|
|
|
|
#pod |
129
|
|
|
|
|
|
|
#pod This is the complete regular expression defining an RFC 2822 email |
130
|
|
|
|
|
|
|
#pod address with an optional preceding display name and optional |
131
|
|
|
|
|
|
|
#pod following comment. |
132
|
|
|
|
|
|
|
#pod |
133
|
|
|
|
|
|
|
#pod =back |
134
|
|
|
|
|
|
|
#pod |
135
|
|
|
|
|
|
|
#pod =cut |
136
|
|
|
|
|
|
|
|
137
|
|
|
|
|
|
|
our $addr_spec = qr/$local_part\@$domain/; |
138
|
|
|
|
|
|
|
our $angle_addr = qr/(?>$cfws*<$addr_spec>$cfws*)/; |
139
|
|
|
|
|
|
|
our $name_addr = qr/(?>$display_name?)$angle_addr/; |
140
|
|
|
|
|
|
|
our $mailbox = qr/(?:$name_addr|$addr_spec)(?>$comment*)/; |
141
|
|
|
|
|
|
|
|
142
|
|
|
|
|
|
|
sub _PHRASE () { 0 } |
143
|
|
|
|
|
|
|
sub _ADDRESS () { 1 } |
144
|
|
|
|
|
|
|
sub _COMMENT () { 2 } |
145
|
|
|
|
|
|
|
sub _ORIGINAL () { 3 } |
146
|
|
|
|
|
|
|
sub _IN_CACHE () { 4 } |
147
|
|
|
|
|
|
|
|
148
|
|
|
|
|
|
|
sub __dump { |
149
|
|
|
|
|
|
|
return { |
150
|
0
|
|
|
0
|
|
0
|
phrase => $_[0][_PHRASE], |
151
|
|
|
|
|
|
|
address => $_[0][_ADDRESS], |
152
|
|
|
|
|
|
|
comment => $_[0][_COMMENT], |
153
|
|
|
|
|
|
|
original => $_[0][_ORIGINAL], |
154
|
|
|
|
|
|
|
} |
155
|
|
|
|
|
|
|
} |
156
|
|
|
|
|
|
|
|
157
|
|
|
|
|
|
|
#pod =head2 Class Methods |
158
|
|
|
|
|
|
|
#pod |
159
|
|
|
|
|
|
|
#pod =over |
160
|
|
|
|
|
|
|
#pod |
161
|
|
|
|
|
|
|
#pod =item parse |
162
|
|
|
|
|
|
|
#pod |
163
|
|
|
|
|
|
|
#pod my @addrs = Email::Address->parse( |
164
|
|
|
|
|
|
|
#pod q[me@local, Casey , "Casey" (West)] |
165
|
|
|
|
|
|
|
#pod ); |
166
|
|
|
|
|
|
|
#pod |
167
|
|
|
|
|
|
|
#pod This method returns a list of C objects it finds in the input |
168
|
|
|
|
|
|
|
#pod string. B that it returns a list, and expects that it may find |
169
|
|
|
|
|
|
|
#pod multiple addresses. The behavior in scalar context is undefined. |
170
|
|
|
|
|
|
|
#pod |
171
|
|
|
|
|
|
|
#pod The specification for an email address allows for infinitely nestable comments. |
172
|
|
|
|
|
|
|
#pod That's nice in theory, but a little over done. By default this module allows |
173
|
|
|
|
|
|
|
#pod for one (C<1>) level of nested comments. If you think you need more, modify the |
174
|
|
|
|
|
|
|
#pod C<$Email::Address::COMMENT_NEST_LEVEL> package variable to allow more. |
175
|
|
|
|
|
|
|
#pod |
176
|
|
|
|
|
|
|
#pod $Email::Address::COMMENT_NEST_LEVEL = 10; # I'm deep |
177
|
|
|
|
|
|
|
#pod |
178
|
|
|
|
|
|
|
#pod The reason for this hardly-limiting limitation is simple: efficiency. |
179
|
|
|
|
|
|
|
#pod |
180
|
|
|
|
|
|
|
#pod Long strings of whitespace can be problematic for this module to parse, a bug |
181
|
|
|
|
|
|
|
#pod which has not yet been adequately addressed. The default behavior is now to |
182
|
|
|
|
|
|
|
#pod collapse multiple spaces into a single space, which avoids this problem. To |
183
|
|
|
|
|
|
|
#pod prevent this behavior, set C<$Email::Address::COLLAPSE_SPACES> to zero. This |
184
|
|
|
|
|
|
|
#pod variable will go away when the bug is resolved properly. |
185
|
|
|
|
|
|
|
#pod |
186
|
|
|
|
|
|
|
#pod In accordance with RFC 822 and its descendants, this module demands that email |
187
|
|
|
|
|
|
|
#pod addresses be ASCII only. Any non-ASCII content in the parsed addresses will |
188
|
|
|
|
|
|
|
#pod cause the parser to return no results. |
189
|
|
|
|
|
|
|
#pod |
190
|
|
|
|
|
|
|
#pod =cut |
191
|
|
|
|
|
|
|
|
192
|
|
|
|
|
|
|
our (%PARSE_CACHE, %FORMAT_CACHE, %NAME_CACHE); |
193
|
|
|
|
|
|
|
my $NOCACHE; |
194
|
|
|
|
|
|
|
|
195
|
|
|
|
|
|
|
sub __get_cached_parse { |
196
|
118
|
50
|
|
118
|
|
323
|
return if $NOCACHE; |
197
|
|
|
|
|
|
|
|
198
|
118
|
|
|
|
|
250
|
my ($class, $line) = @_; |
199
|
|
|
|
|
|
|
|
200
|
118
|
100
|
|
|
|
441
|
return @{$PARSE_CACHE{$line}} if exists $PARSE_CACHE{$line}; |
|
2
|
|
|
|
|
8
|
|
201
|
116
|
|
|
|
|
412
|
return; |
202
|
|
|
|
|
|
|
} |
203
|
|
|
|
|
|
|
|
204
|
|
|
|
|
|
|
sub __cache_parse { |
205
|
116
|
50
|
|
116
|
|
272
|
return if $NOCACHE; |
206
|
|
|
|
|
|
|
|
207
|
116
|
|
|
|
|
266
|
my ($class, $line, $addrs) = @_; |
208
|
|
|
|
|
|
|
|
209
|
116
|
|
|
|
|
375
|
$PARSE_CACHE{$line} = $addrs; |
210
|
|
|
|
|
|
|
} |
211
|
|
|
|
|
|
|
|
212
|
|
|
|
|
|
|
sub parse { |
213
|
119
|
|
|
119
|
1
|
396049
|
my ($class, $line) = @_; |
214
|
119
|
100
|
|
|
|
411
|
return unless $line; |
215
|
|
|
|
|
|
|
|
216
|
118
|
50
|
|
|
|
1085
|
$line =~ s/[ \t]+/ /g if $COLLAPSE_SPACES; |
217
|
|
|
|
|
|
|
|
218
|
118
|
100
|
|
|
|
446
|
if (my @cached = $class->__get_cached_parse($line)) { |
219
|
2
|
|
|
|
|
7
|
return @cached; |
220
|
|
|
|
|
|
|
} |
221
|
|
|
|
|
|
|
|
222
|
116
|
|
|
|
|
242
|
my %mailboxes; |
223
|
116
|
|
|
|
|
294
|
my $str = $line; |
224
|
116
|
100
|
|
|
|
8077
|
$str =~ s!($name_addr(?>$comment*))!$mailboxes{pos($str)} = $1; ',' x length $1!ego |
|
198
|
|
|
|
|
824
|
|
|
198
|
|
|
|
|
1868
|
|
225
|
|
|
|
|
|
|
if $str =~ /$angle_addr/; |
226
|
116
|
|
|
|
|
3787
|
$str =~ s!($addr_spec(?>$comment*))!$mailboxes{pos($str)} = $1; ',' x length $1!ego; |
|
46
|
|
|
|
|
179
|
|
|
46
|
|
|
|
|
262
|
|
227
|
116
|
|
|
|
|
654
|
my @mailboxes = map { $mailboxes{$_} } sort { $a <=> $b } keys %mailboxes; |
|
244
|
|
|
|
|
648
|
|
|
197
|
|
|
|
|
547
|
|
228
|
|
|
|
|
|
|
|
229
|
116
|
|
|
|
|
232
|
my @addrs; |
230
|
116
|
|
|
|
|
302
|
foreach (@mailboxes) { |
231
|
244
|
|
|
|
|
460
|
my $original = $_; |
232
|
|
|
|
|
|
|
|
233
|
244
|
|
|
|
|
831
|
my @comments = /($comment)/go; |
234
|
244
|
100
|
|
|
|
592
|
s/$comment//go if @comments; |
235
|
|
|
|
|
|
|
|
236
|
244
|
|
|
|
|
463
|
my ($user, $host, $com); |
237
|
244
|
100
|
|
|
|
3869
|
($user, $host) = ($1, $2) if s/<($local_part)\@($domain)>\s*\z//o; |
238
|
244
|
100
|
66
|
|
|
1140
|
if (! defined($user) || ! defined($host)) { |
239
|
46
|
|
|
|
|
1716
|
s/($local_part)\@($domain)//o; |
240
|
46
|
|
|
|
|
194
|
($user, $host) = ($1, $2); |
241
|
|
|
|
|
|
|
} |
242
|
|
|
|
|
|
|
|
243
|
10
|
100
|
|
10
|
|
5808
|
next if $user =~ /\P{ASCII}/; |
|
10
|
|
|
|
|
147
|
|
|
10
|
|
|
|
|
148
|
|
|
244
|
|
|
|
|
710
|
|
244
|
240
|
100
|
|
|
|
579
|
next if $host =~ /\P{ASCII}/; |
245
|
|
|
|
|
|
|
|
246
|
239
|
|
|
|
|
3204
|
my ($phrase) = /($display_name)/o; |
247
|
|
|
|
|
|
|
|
248
|
239
|
|
|
|
|
577
|
for ( $phrase, $host, $user, @comments ) { |
249
|
727
|
100
|
|
|
|
1272
|
next unless defined $_; |
250
|
651
|
|
|
|
|
1295
|
s/^\s+//; |
251
|
651
|
|
|
|
|
1379
|
s/\s+$//; |
252
|
651
|
50
|
|
|
|
1346
|
$_ = undef unless length $_; |
253
|
|
|
|
|
|
|
} |
254
|
|
|
|
|
|
|
|
255
|
239
|
100
|
|
|
|
534
|
$phrase =~ s/\\(.)/$1/g if $phrase; |
256
|
|
|
|
|
|
|
|
257
|
239
|
|
|
|
|
515
|
my $new_comment = join q{ }, @comments; |
258
|
239
|
|
|
|
|
948
|
push @addrs, |
259
|
|
|
|
|
|
|
$class->new($phrase, "$user\@$host", $new_comment, $original); |
260
|
239
|
|
|
|
|
1152
|
$addrs[-1]->[_IN_CACHE] = [ \$line, $#addrs ] |
261
|
|
|
|
|
|
|
} |
262
|
|
|
|
|
|
|
|
263
|
116
|
|
|
|
|
465
|
$class->__cache_parse($line, \@addrs); |
264
|
116
|
|
|
|
|
617
|
return @addrs; |
265
|
|
|
|
|
|
|
} |
266
|
|
|
|
|
|
|
|
267
|
|
|
|
|
|
|
#pod =item new |
268
|
|
|
|
|
|
|
#pod |
269
|
|
|
|
|
|
|
#pod my $address = Email::Address->new(undef, 'casey@local'); |
270
|
|
|
|
|
|
|
#pod my $address = Email::Address->new('Casey West', 'casey@local'); |
271
|
|
|
|
|
|
|
#pod my $address = Email::Address->new(undef, 'casey@local', '(Casey)'); |
272
|
|
|
|
|
|
|
#pod |
273
|
|
|
|
|
|
|
#pod Constructs and returns a new C object. Takes four |
274
|
|
|
|
|
|
|
#pod positional arguments: phrase, email, and comment, and original string. |
275
|
|
|
|
|
|
|
#pod |
276
|
|
|
|
|
|
|
#pod The original string should only really be set using C. |
277
|
|
|
|
|
|
|
#pod |
278
|
|
|
|
|
|
|
#pod =cut |
279
|
|
|
|
|
|
|
|
280
|
|
|
|
|
|
|
sub new { |
281
|
693
|
|
|
693
|
1
|
309488
|
my ($class, $phrase, $email, $comment, $orig) = @_; |
282
|
693
|
100
|
|
|
|
2166
|
$phrase =~ s/\A"(.+)"\z/$1/ if $phrase; |
283
|
|
|
|
|
|
|
|
284
|
693
|
|
|
|
|
2603
|
bless [ $phrase, $email, $comment, $orig ] => $class; |
285
|
|
|
|
|
|
|
} |
286
|
|
|
|
|
|
|
|
287
|
|
|
|
|
|
|
#pod =item purge_cache |
288
|
|
|
|
|
|
|
#pod |
289
|
|
|
|
|
|
|
#pod Email::Address->purge_cache; |
290
|
|
|
|
|
|
|
#pod |
291
|
|
|
|
|
|
|
#pod One way this module stays fast is with internal caches. Caches live |
292
|
|
|
|
|
|
|
#pod in memory and there is the remote possibility that you will have a |
293
|
|
|
|
|
|
|
#pod memory problem. On the off chance that you think you're one of those |
294
|
|
|
|
|
|
|
#pod people, this class method will empty those caches. |
295
|
|
|
|
|
|
|
#pod |
296
|
|
|
|
|
|
|
#pod I've loaded over 12000 objects and not encountered a memory problem. |
297
|
|
|
|
|
|
|
#pod |
298
|
|
|
|
|
|
|
#pod =cut |
299
|
|
|
|
|
|
|
|
300
|
|
|
|
|
|
|
sub purge_cache { |
301
|
0
|
|
|
0
|
1
|
0
|
%NAME_CACHE = (); |
302
|
0
|
|
|
|
|
0
|
%FORMAT_CACHE = (); |
303
|
0
|
|
|
|
|
0
|
%PARSE_CACHE = (); |
304
|
|
|
|
|
|
|
} |
305
|
|
|
|
|
|
|
|
306
|
|
|
|
|
|
|
#pod =item disable_cache |
307
|
|
|
|
|
|
|
#pod |
308
|
|
|
|
|
|
|
#pod =item enable_cache |
309
|
|
|
|
|
|
|
#pod |
310
|
|
|
|
|
|
|
#pod Email::Address->disable_cache if memory_low(); |
311
|
|
|
|
|
|
|
#pod |
312
|
|
|
|
|
|
|
#pod If you'd rather not cache address parses at all, you can disable (and |
313
|
|
|
|
|
|
|
#pod re-enable) the Email::Address cache with these methods. The cache is enabled |
314
|
|
|
|
|
|
|
#pod by default. |
315
|
|
|
|
|
|
|
#pod |
316
|
|
|
|
|
|
|
#pod =cut |
317
|
|
|
|
|
|
|
|
318
|
|
|
|
|
|
|
sub disable_cache { |
319
|
0
|
|
|
0
|
1
|
0
|
my ($class) = @_; |
320
|
0
|
|
|
|
|
0
|
$class->purge_cache; |
321
|
0
|
|
|
|
|
0
|
$NOCACHE = 1; |
322
|
|
|
|
|
|
|
} |
323
|
|
|
|
|
|
|
|
324
|
|
|
|
|
|
|
sub enable_cache { |
325
|
0
|
|
|
0
|
1
|
0
|
$NOCACHE = undef; |
326
|
|
|
|
|
|
|
} |
327
|
|
|
|
|
|
|
|
328
|
|
|
|
|
|
|
#pod =back |
329
|
|
|
|
|
|
|
#pod |
330
|
|
|
|
|
|
|
#pod =head2 Instance Methods |
331
|
|
|
|
|
|
|
#pod |
332
|
|
|
|
|
|
|
#pod =over 4 |
333
|
|
|
|
|
|
|
#pod |
334
|
|
|
|
|
|
|
#pod =item phrase |
335
|
|
|
|
|
|
|
#pod |
336
|
|
|
|
|
|
|
#pod my $phrase = $address->phrase; |
337
|
|
|
|
|
|
|
#pod $address->phrase( "Me oh my" ); |
338
|
|
|
|
|
|
|
#pod |
339
|
|
|
|
|
|
|
#pod Accessor and mutator for the phrase portion of an address. |
340
|
|
|
|
|
|
|
#pod |
341
|
|
|
|
|
|
|
#pod =item address |
342
|
|
|
|
|
|
|
#pod |
343
|
|
|
|
|
|
|
#pod my $addr = $address->address; |
344
|
|
|
|
|
|
|
#pod $addr->address( "me@PROTECTED.com" ); |
345
|
|
|
|
|
|
|
#pod |
346
|
|
|
|
|
|
|
#pod Accessor and mutator for the address portion of an address. |
347
|
|
|
|
|
|
|
#pod |
348
|
|
|
|
|
|
|
#pod =item comment |
349
|
|
|
|
|
|
|
#pod |
350
|
|
|
|
|
|
|
#pod my $comment = $address->comment; |
351
|
|
|
|
|
|
|
#pod $address->comment( "(Work address)" ); |
352
|
|
|
|
|
|
|
#pod |
353
|
|
|
|
|
|
|
#pod Accessor and mutator for the comment portion of an address. |
354
|
|
|
|
|
|
|
#pod |
355
|
|
|
|
|
|
|
#pod =item original |
356
|
|
|
|
|
|
|
#pod |
357
|
|
|
|
|
|
|
#pod my $orig = $address->original; |
358
|
|
|
|
|
|
|
#pod |
359
|
|
|
|
|
|
|
#pod Accessor for the original address found when parsing, or passed |
360
|
|
|
|
|
|
|
#pod to C. |
361
|
|
|
|
|
|
|
#pod |
362
|
|
|
|
|
|
|
#pod =item host |
363
|
|
|
|
|
|
|
#pod |
364
|
|
|
|
|
|
|
#pod my $host = $address->host; |
365
|
|
|
|
|
|
|
#pod |
366
|
|
|
|
|
|
|
#pod Accessor for the host portion of an address's address. |
367
|
|
|
|
|
|
|
#pod |
368
|
|
|
|
|
|
|
#pod =item user |
369
|
|
|
|
|
|
|
#pod |
370
|
|
|
|
|
|
|
#pod my $user = $address->user; |
371
|
|
|
|
|
|
|
#pod |
372
|
|
|
|
|
|
|
#pod Accessor for the user portion of an address's address. |
373
|
|
|
|
|
|
|
#pod |
374
|
|
|
|
|
|
|
#pod =cut |
375
|
|
|
|
|
|
|
|
376
|
|
|
|
|
|
|
BEGIN { |
377
|
10
|
|
|
10
|
|
62
|
my %_INDEX = ( |
378
|
|
|
|
|
|
|
phrase => _PHRASE, |
379
|
|
|
|
|
|
|
address => _ADDRESS, |
380
|
|
|
|
|
|
|
comment => _COMMENT, |
381
|
|
|
|
|
|
|
original => _ORIGINAL, |
382
|
|
|
|
|
|
|
); |
383
|
|
|
|
|
|
|
|
384
|
10
|
|
|
|
|
42
|
for my $method (keys %_INDEX) { |
385
|
10
|
|
|
10
|
|
209498
|
no strict 'refs'; |
|
10
|
|
|
|
|
26
|
|
|
10
|
|
|
|
|
1563
|
|
386
|
40
|
|
|
|
|
75
|
my $index = $_INDEX{ $method }; |
387
|
|
|
|
|
|
|
*$method = sub { |
388
|
229
|
100
|
|
229
|
|
177942
|
if ($_[1]) { |
389
|
1
|
50
|
|
|
|
4
|
if ($_[0][_IN_CACHE]) { |
390
|
1
|
|
|
|
|
2
|
my $replicant = bless [ @{$_[0]} ] => ref $_[0]; |
|
1
|
|
|
|
|
5
|
|
391
|
1
|
|
|
|
|
2
|
$PARSE_CACHE{ ${ $_[0][_IN_CACHE][0] } }[ $_[0][_IN_CACHE][1] ] |
|
1
|
|
|
|
|
4
|
|
392
|
|
|
|
|
|
|
= $replicant; |
393
|
1
|
|
|
|
|
3
|
$_[0][_IN_CACHE] = undef; |
394
|
|
|
|
|
|
|
} |
395
|
1
|
|
|
|
|
3
|
$_[0]->[ $index ] = $_[1]; |
396
|
|
|
|
|
|
|
} else { |
397
|
228
|
|
|
|
|
912
|
$_[0]->[ $index ]; |
398
|
|
|
|
|
|
|
} |
399
|
40
|
|
|
|
|
1150
|
}; |
400
|
|
|
|
|
|
|
} |
401
|
|
|
|
|
|
|
} |
402
|
|
|
|
|
|
|
|
403
|
0
|
|
|
0
|
1
|
0
|
sub host { ($_[0]->[_ADDRESS] =~ /\@($domain)/o)[0] } |
404
|
0
|
|
|
0
|
1
|
0
|
sub user { ($_[0]->[_ADDRESS] =~ /($local_part)\@/o)[0] } |
405
|
|
|
|
|
|
|
|
406
|
|
|
|
|
|
|
#pod =pod |
407
|
|
|
|
|
|
|
#pod |
408
|
|
|
|
|
|
|
#pod =item format |
409
|
|
|
|
|
|
|
#pod |
410
|
|
|
|
|
|
|
#pod my $printable = $address->format; |
411
|
|
|
|
|
|
|
#pod |
412
|
|
|
|
|
|
|
#pod Returns a properly formatted RFC 2822 address representing the |
413
|
|
|
|
|
|
|
#pod object. |
414
|
|
|
|
|
|
|
#pod |
415
|
|
|
|
|
|
|
#pod =cut |
416
|
|
|
|
|
|
|
|
417
|
|
|
|
|
|
|
sub format { |
418
|
10
|
|
|
10
|
1
|
68
|
my $cache_str = do { no warnings 'uninitialized'; "@{$_[0]}" }; |
|
10
|
|
|
2014
|
|
23
|
|
|
10
|
|
|
|
|
4071
|
|
|
2014
|
|
|
|
|
573948
|
|
|
2014
|
|
|
|
|
2697
|
|
|
2014
|
|
|
|
|
6415
|
|
419
|
2014
|
100
|
|
|
|
8298
|
return $FORMAT_CACHE{$cache_str} if exists $FORMAT_CACHE{$cache_str}; |
420
|
334
|
|
|
|
|
828
|
$FORMAT_CACHE{$cache_str} = $_[0]->_format; |
421
|
|
|
|
|
|
|
} |
422
|
|
|
|
|
|
|
|
423
|
|
|
|
|
|
|
sub _format { |
424
|
334
|
|
|
334
|
|
597
|
my ($self) = @_; |
425
|
|
|
|
|
|
|
|
426
|
334
|
100
|
100
|
|
|
1769
|
unless ( |
|
|
|
100
|
|
|
|
|
|
|
|
100
|
|
|
|
|
427
|
|
|
|
|
|
|
defined $self->[_PHRASE] && length $self->[_PHRASE] |
428
|
|
|
|
|
|
|
|| |
429
|
|
|
|
|
|
|
defined $self->[_COMMENT] && length $self->[_COMMENT] |
430
|
|
|
|
|
|
|
) { |
431
|
86
|
100
|
|
|
|
519
|
return defined $self->[_ADDRESS] ? $self->[_ADDRESS] : ''; |
432
|
|
|
|
|
|
|
} |
433
|
|
|
|
|
|
|
|
434
|
248
|
100
|
|
|
|
670
|
my $comment = defined $self->[_COMMENT] ? $self->[_COMMENT] : ''; |
435
|
248
|
100
|
100
|
|
|
669
|
$comment = "($comment)" if length $comment and $comment !~ /\A\(.*\)\z/; |
436
|
|
|
|
|
|
|
|
437
|
248
|
50
|
|
|
|
571
|
my $format = sprintf q{%s <%s> %s}, |
438
|
|
|
|
|
|
|
$self->_enquoted_phrase, |
439
|
|
|
|
|
|
|
(defined $self->[_ADDRESS] ? $self->[_ADDRESS] : ''), |
440
|
|
|
|
|
|
|
$comment; |
441
|
|
|
|
|
|
|
|
442
|
248
|
|
|
|
|
818
|
$format =~ s/^\s+//; |
443
|
248
|
|
|
|
|
1075
|
$format =~ s/\s+$//; |
444
|
|
|
|
|
|
|
|
445
|
248
|
|
|
|
|
1129
|
return $format; |
446
|
|
|
|
|
|
|
} |
447
|
|
|
|
|
|
|
|
448
|
|
|
|
|
|
|
sub _enquoted_phrase { |
449
|
248
|
|
|
248
|
|
410
|
my ($self) = @_; |
450
|
|
|
|
|
|
|
|
451
|
248
|
|
|
|
|
445
|
my $phrase = $self->[_PHRASE]; |
452
|
|
|
|
|
|
|
|
453
|
248
|
100
|
66
|
|
|
869
|
return '' unless defined $phrase and length $phrase; |
454
|
|
|
|
|
|
|
|
455
|
|
|
|
|
|
|
# if it's encoded -- rjbs, 2007-02-28 |
456
|
247
|
100
|
|
|
|
711
|
return $phrase if $phrase =~ /\A=\?.+\?=\z/; |
457
|
|
|
|
|
|
|
|
458
|
246
|
|
|
|
|
464
|
$phrase =~ s/\A"(.+)"\z/$1/; |
459
|
246
|
|
|
|
|
577
|
$phrase =~ s/([\\"])/\\$1/g; |
460
|
|
|
|
|
|
|
|
461
|
246
|
|
|
|
|
1514
|
return qq{"$phrase"}; |
462
|
|
|
|
|
|
|
} |
463
|
|
|
|
|
|
|
|
464
|
|
|
|
|
|
|
#pod =item name |
465
|
|
|
|
|
|
|
#pod |
466
|
|
|
|
|
|
|
#pod my $name = $address->name; |
467
|
|
|
|
|
|
|
#pod |
468
|
|
|
|
|
|
|
#pod This method tries very hard to determine the name belonging to the address. |
469
|
|
|
|
|
|
|
#pod First the C is checked. If that doesn't work out the C |
470
|
|
|
|
|
|
|
#pod is looked into. If that still doesn't work out, the C portion of |
471
|
|
|
|
|
|
|
#pod the C is returned. |
472
|
|
|
|
|
|
|
#pod |
473
|
|
|
|
|
|
|
#pod This method does B try to massage any name it identifies and instead |
474
|
|
|
|
|
|
|
#pod leaves that up to someone else. Who is it to decide if someone wants their |
475
|
|
|
|
|
|
|
#pod name capitalized, or if they're Irish? |
476
|
|
|
|
|
|
|
#pod |
477
|
|
|
|
|
|
|
#pod =cut |
478
|
|
|
|
|
|
|
|
479
|
|
|
|
|
|
|
sub name { |
480
|
10
|
|
|
10
|
1
|
78
|
my $cache_str = do { no warnings 'uninitialized'; "@{$_[0]}" }; |
|
10
|
|
|
663
|
|
17
|
|
|
10
|
|
|
|
|
2995
|
|
|
663
|
|
|
|
|
938
|
|
|
663
|
|
|
|
|
844
|
|
|
663
|
|
|
|
|
1822
|
|
481
|
663
|
100
|
|
|
|
2287
|
return $NAME_CACHE{$cache_str} if exists $NAME_CACHE{$cache_str}; |
482
|
|
|
|
|
|
|
|
483
|
314
|
|
|
|
|
551
|
my ($self) = @_; |
484
|
314
|
|
|
|
|
483
|
my $name = q{}; |
485
|
314
|
100
|
|
|
|
888
|
if ( $name = $self->[_PHRASE] ) { |
|
|
50
|
|
|
|
|
|
486
|
233
|
|
|
|
|
410
|
$name =~ s/^"//; |
487
|
233
|
|
|
|
|
411
|
$name =~ s/"$//; |
488
|
233
|
|
|
|
|
390
|
$name =~ s/($quoted_pair)/substr $1, -1/goe; |
|
0
|
|
|
|
|
0
|
|
489
|
|
|
|
|
|
|
} elsif ( $name = $self->[_COMMENT] ) { |
490
|
0
|
|
|
|
|
0
|
$name =~ s/^\(//; |
491
|
0
|
|
|
|
|
0
|
$name =~ s/\)$//; |
492
|
0
|
|
|
|
|
0
|
$name =~ s/($quoted_pair)/substr $1, -1/goe; |
|
0
|
|
|
|
|
0
|
|
493
|
0
|
|
|
|
|
0
|
$name =~ s/$comment/ /go; |
494
|
|
|
|
|
|
|
} else { |
495
|
81
|
|
|
|
|
935
|
($name) = $self->[_ADDRESS] =~ /($local_part)\@/o; |
496
|
|
|
|
|
|
|
} |
497
|
314
|
|
|
|
|
1024
|
$NAME_CACHE{$cache_str} = $name; |
498
|
|
|
|
|
|
|
} |
499
|
|
|
|
|
|
|
|
500
|
|
|
|
|
|
|
#pod =back |
501
|
|
|
|
|
|
|
#pod |
502
|
|
|
|
|
|
|
#pod =head2 Overloaded Operators |
503
|
|
|
|
|
|
|
#pod |
504
|
|
|
|
|
|
|
#pod =over 4 |
505
|
|
|
|
|
|
|
#pod |
506
|
|
|
|
|
|
|
#pod =item stringify |
507
|
|
|
|
|
|
|
#pod |
508
|
|
|
|
|
|
|
#pod print "I have your email address, $address."; |
509
|
|
|
|
|
|
|
#pod |
510
|
|
|
|
|
|
|
#pod Objects stringify to C by default. It's possible that you don't |
511
|
|
|
|
|
|
|
#pod like that idea. Okay, then, you can change it by modifying |
512
|
|
|
|
|
|
|
#pod C<$Email:Address::STRINGIFY>. Please consider modifying this package |
513
|
|
|
|
|
|
|
#pod variable using C. You might step on someone else's toes if you |
514
|
|
|
|
|
|
|
#pod don't. |
515
|
|
|
|
|
|
|
#pod |
516
|
|
|
|
|
|
|
#pod { |
517
|
|
|
|
|
|
|
#pod local $Email::Address::STRINGIFY = 'host'; |
518
|
|
|
|
|
|
|
#pod print "I have your address, $address."; |
519
|
|
|
|
|
|
|
#pod # geeknest.com |
520
|
|
|
|
|
|
|
#pod } |
521
|
|
|
|
|
|
|
#pod print "I have your address, $address."; |
522
|
|
|
|
|
|
|
#pod # "Casey West" |
523
|
|
|
|
|
|
|
#pod |
524
|
|
|
|
|
|
|
#pod Modifying this package variable is now deprecated. Subclassing is now the |
525
|
|
|
|
|
|
|
#pod recommended approach. |
526
|
|
|
|
|
|
|
#pod |
527
|
|
|
|
|
|
|
#pod =cut |
528
|
|
|
|
|
|
|
|
529
|
|
|
|
|
|
|
sub as_string { |
530
|
669
|
50
|
|
669
|
0
|
3831
|
warn 'altering $Email::Address::STRINGIFY is deprecated; subclass instead' |
531
|
|
|
|
|
|
|
if $STRINGIFY ne 'format'; |
532
|
|
|
|
|
|
|
|
533
|
669
|
|
|
|
|
2164
|
$_[0]->can($STRINGIFY)->($_[0]); |
534
|
|
|
|
|
|
|
} |
535
|
|
|
|
|
|
|
|
536
|
10
|
|
|
10
|
|
7381
|
use overload '""' => 'as_string', fallback => 1; |
|
10
|
|
|
|
|
5957
|
|
|
10
|
|
|
|
|
70
|
|
537
|
|
|
|
|
|
|
|
538
|
|
|
|
|
|
|
#pod =pod |
539
|
|
|
|
|
|
|
#pod |
540
|
|
|
|
|
|
|
#pod =back |
541
|
|
|
|
|
|
|
#pod |
542
|
|
|
|
|
|
|
#pod =cut |
543
|
|
|
|
|
|
|
|
544
|
|
|
|
|
|
|
1; |
545
|
|
|
|
|
|
|
|
546
|
|
|
|
|
|
|
=pod |
547
|
|
|
|
|
|
|
|
548
|
|
|
|
|
|
|
=encoding UTF-8 |
549
|
|
|
|
|
|
|
|
550
|
|
|
|
|
|
|
=head1 NAME |
551
|
|
|
|
|
|
|
|
552
|
|
|
|
|
|
|
Email::Address - RFC 2822 Address Parsing and Creation |
553
|
|
|
|
|
|
|
|
554
|
|
|
|
|
|
|
=head1 VERSION |
555
|
|
|
|
|
|
|
|
556
|
|
|
|
|
|
|
version 1.912 |
557
|
|
|
|
|
|
|
|
558
|
|
|
|
|
|
|
=head1 SYNOPSIS |
559
|
|
|
|
|
|
|
|
560
|
|
|
|
|
|
|
use Email::Address; |
561
|
|
|
|
|
|
|
|
562
|
|
|
|
|
|
|
my @addresses = Email::Address->parse($line); |
563
|
|
|
|
|
|
|
my $address = Email::Address->new(Casey => 'casey@localhost'); |
564
|
|
|
|
|
|
|
|
565
|
|
|
|
|
|
|
print $address->format; |
566
|
|
|
|
|
|
|
|
567
|
|
|
|
|
|
|
=head1 DESCRIPTION |
568
|
|
|
|
|
|
|
|
569
|
|
|
|
|
|
|
This class implements a regex-based RFC 2822 parser that locates email |
570
|
|
|
|
|
|
|
addresses in strings and returns a list of C objects found. |
571
|
|
|
|
|
|
|
Alternatively you may construct objects manually. The goal of this software is |
572
|
|
|
|
|
|
|
to be correct, and very very fast. |
573
|
|
|
|
|
|
|
|
574
|
|
|
|
|
|
|
Version 1.909 and earlier of this module had vulnerabilies |
575
|
|
|
|
|
|
|
(L) |
576
|
|
|
|
|
|
|
and (L) |
577
|
|
|
|
|
|
|
which allowed specially constructed email to cause a denial of service. The |
578
|
|
|
|
|
|
|
reported vulnerabilities and some other pathalogical cases (meaning they really |
579
|
|
|
|
|
|
|
shouldn't occur in normal email) have been addressed in version 1.910 and newer. |
580
|
|
|
|
|
|
|
If you're running version 1.909 or older, you should update! |
581
|
|
|
|
|
|
|
|
582
|
|
|
|
|
|
|
Alternatively, you could switch to L|Email::Address::XS> |
583
|
|
|
|
|
|
|
which has a backward compatible API. |
584
|
|
|
|
|
|
|
|
585
|
|
|
|
|
|
|
=head2 Package Variables |
586
|
|
|
|
|
|
|
|
587
|
|
|
|
|
|
|
B Email isn't easy (if even possible) to parse with a regex, I
|
588
|
|
|
|
|
|
|
least> if you're on a C prior to 5.10.0. Providing regular expressions |
589
|
|
|
|
|
|
|
for use by other programs isn't a great idea, because it makes it hard to |
590
|
|
|
|
|
|
|
improve the parser without breaking the "it's a regex" feature. Using these |
591
|
|
|
|
|
|
|
regular expressions is not encouraged, and methods like C<< |
592
|
|
|
|
|
|
|
Email::Address->is_addr_spec >> should be provided in the future. |
593
|
|
|
|
|
|
|
|
594
|
|
|
|
|
|
|
Several regular expressions used in this package are useful to others. |
595
|
|
|
|
|
|
|
For convenience, these variables are declared as package variables that |
596
|
|
|
|
|
|
|
you may access from your program. |
597
|
|
|
|
|
|
|
|
598
|
|
|
|
|
|
|
These regular expressions conform to the rules specified in RFC 2822. |
599
|
|
|
|
|
|
|
|
600
|
|
|
|
|
|
|
You can access these variables using the full namespace. If you want |
601
|
|
|
|
|
|
|
short names, define them yourself. |
602
|
|
|
|
|
|
|
|
603
|
|
|
|
|
|
|
my $addr_spec = $Email::Address::addr_spec; |
604
|
|
|
|
|
|
|
|
605
|
|
|
|
|
|
|
=over 4 |
606
|
|
|
|
|
|
|
|
607
|
|
|
|
|
|
|
=item $Email::Address::addr_spec |
608
|
|
|
|
|
|
|
|
609
|
|
|
|
|
|
|
This regular expression defined what an email address is allowed to |
610
|
|
|
|
|
|
|
look like. |
611
|
|
|
|
|
|
|
|
612
|
|
|
|
|
|
|
=item $Email::Address::angle_addr |
613
|
|
|
|
|
|
|
|
614
|
|
|
|
|
|
|
This regular expression defines an C<$addr_spec> wrapped in angle |
615
|
|
|
|
|
|
|
brackets. |
616
|
|
|
|
|
|
|
|
617
|
|
|
|
|
|
|
=item $Email::Address::name_addr |
618
|
|
|
|
|
|
|
|
619
|
|
|
|
|
|
|
This regular expression defines what an email address can look like |
620
|
|
|
|
|
|
|
with an optional preceding display name, also known as the C. |
621
|
|
|
|
|
|
|
|
622
|
|
|
|
|
|
|
=item $Email::Address::mailbox |
623
|
|
|
|
|
|
|
|
624
|
|
|
|
|
|
|
This is the complete regular expression defining an RFC 2822 email |
625
|
|
|
|
|
|
|
address with an optional preceding display name and optional |
626
|
|
|
|
|
|
|
following comment. |
627
|
|
|
|
|
|
|
|
628
|
|
|
|
|
|
|
=back |
629
|
|
|
|
|
|
|
|
630
|
|
|
|
|
|
|
=head2 Class Methods |
631
|
|
|
|
|
|
|
|
632
|
|
|
|
|
|
|
=over |
633
|
|
|
|
|
|
|
|
634
|
|
|
|
|
|
|
=item parse |
635
|
|
|
|
|
|
|
|
636
|
|
|
|
|
|
|
my @addrs = Email::Address->parse( |
637
|
|
|
|
|
|
|
q[me@local, Casey , "Casey" (West)] |
638
|
|
|
|
|
|
|
); |
639
|
|
|
|
|
|
|
|
640
|
|
|
|
|
|
|
This method returns a list of C objects it finds in the input |
641
|
|
|
|
|
|
|
string. B that it returns a list, and expects that it may find |
642
|
|
|
|
|
|
|
multiple addresses. The behavior in scalar context is undefined. |
643
|
|
|
|
|
|
|
|
644
|
|
|
|
|
|
|
The specification for an email address allows for infinitely nestable comments. |
645
|
|
|
|
|
|
|
That's nice in theory, but a little over done. By default this module allows |
646
|
|
|
|
|
|
|
for one (C<1>) level of nested comments. If you think you need more, modify the |
647
|
|
|
|
|
|
|
C<$Email::Address::COMMENT_NEST_LEVEL> package variable to allow more. |
648
|
|
|
|
|
|
|
|
649
|
|
|
|
|
|
|
$Email::Address::COMMENT_NEST_LEVEL = 10; # I'm deep |
650
|
|
|
|
|
|
|
|
651
|
|
|
|
|
|
|
The reason for this hardly-limiting limitation is simple: efficiency. |
652
|
|
|
|
|
|
|
|
653
|
|
|
|
|
|
|
Long strings of whitespace can be problematic for this module to parse, a bug |
654
|
|
|
|
|
|
|
which has not yet been adequately addressed. The default behavior is now to |
655
|
|
|
|
|
|
|
collapse multiple spaces into a single space, which avoids this problem. To |
656
|
|
|
|
|
|
|
prevent this behavior, set C<$Email::Address::COLLAPSE_SPACES> to zero. This |
657
|
|
|
|
|
|
|
variable will go away when the bug is resolved properly. |
658
|
|
|
|
|
|
|
|
659
|
|
|
|
|
|
|
In accordance with RFC 822 and its descendants, this module demands that email |
660
|
|
|
|
|
|
|
addresses be ASCII only. Any non-ASCII content in the parsed addresses will |
661
|
|
|
|
|
|
|
cause the parser to return no results. |
662
|
|
|
|
|
|
|
|
663
|
|
|
|
|
|
|
=item new |
664
|
|
|
|
|
|
|
|
665
|
|
|
|
|
|
|
my $address = Email::Address->new(undef, 'casey@local'); |
666
|
|
|
|
|
|
|
my $address = Email::Address->new('Casey West', 'casey@local'); |
667
|
|
|
|
|
|
|
my $address = Email::Address->new(undef, 'casey@local', '(Casey)'); |
668
|
|
|
|
|
|
|
|
669
|
|
|
|
|
|
|
Constructs and returns a new C object. Takes four |
670
|
|
|
|
|
|
|
positional arguments: phrase, email, and comment, and original string. |
671
|
|
|
|
|
|
|
|
672
|
|
|
|
|
|
|
The original string should only really be set using C. |
673
|
|
|
|
|
|
|
|
674
|
|
|
|
|
|
|
=item purge_cache |
675
|
|
|
|
|
|
|
|
676
|
|
|
|
|
|
|
Email::Address->purge_cache; |
677
|
|
|
|
|
|
|
|
678
|
|
|
|
|
|
|
One way this module stays fast is with internal caches. Caches live |
679
|
|
|
|
|
|
|
in memory and there is the remote possibility that you will have a |
680
|
|
|
|
|
|
|
memory problem. On the off chance that you think you're one of those |
681
|
|
|
|
|
|
|
people, this class method will empty those caches. |
682
|
|
|
|
|
|
|
|
683
|
|
|
|
|
|
|
I've loaded over 12000 objects and not encountered a memory problem. |
684
|
|
|
|
|
|
|
|
685
|
|
|
|
|
|
|
=item disable_cache |
686
|
|
|
|
|
|
|
|
687
|
|
|
|
|
|
|
=item enable_cache |
688
|
|
|
|
|
|
|
|
689
|
|
|
|
|
|
|
Email::Address->disable_cache if memory_low(); |
690
|
|
|
|
|
|
|
|
691
|
|
|
|
|
|
|
If you'd rather not cache address parses at all, you can disable (and |
692
|
|
|
|
|
|
|
re-enable) the Email::Address cache with these methods. The cache is enabled |
693
|
|
|
|
|
|
|
by default. |
694
|
|
|
|
|
|
|
|
695
|
|
|
|
|
|
|
=back |
696
|
|
|
|
|
|
|
|
697
|
|
|
|
|
|
|
=head2 Instance Methods |
698
|
|
|
|
|
|
|
|
699
|
|
|
|
|
|
|
=over 4 |
700
|
|
|
|
|
|
|
|
701
|
|
|
|
|
|
|
=item phrase |
702
|
|
|
|
|
|
|
|
703
|
|
|
|
|
|
|
my $phrase = $address->phrase; |
704
|
|
|
|
|
|
|
$address->phrase( "Me oh my" ); |
705
|
|
|
|
|
|
|
|
706
|
|
|
|
|
|
|
Accessor and mutator for the phrase portion of an address. |
707
|
|
|
|
|
|
|
|
708
|
|
|
|
|
|
|
=item address |
709
|
|
|
|
|
|
|
|
710
|
|
|
|
|
|
|
my $addr = $address->address; |
711
|
|
|
|
|
|
|
$addr->address( "me@PROTECTED.com" ); |
712
|
|
|
|
|
|
|
|
713
|
|
|
|
|
|
|
Accessor and mutator for the address portion of an address. |
714
|
|
|
|
|
|
|
|
715
|
|
|
|
|
|
|
=item comment |
716
|
|
|
|
|
|
|
|
717
|
|
|
|
|
|
|
my $comment = $address->comment; |
718
|
|
|
|
|
|
|
$address->comment( "(Work address)" ); |
719
|
|
|
|
|
|
|
|
720
|
|
|
|
|
|
|
Accessor and mutator for the comment portion of an address. |
721
|
|
|
|
|
|
|
|
722
|
|
|
|
|
|
|
=item original |
723
|
|
|
|
|
|
|
|
724
|
|
|
|
|
|
|
my $orig = $address->original; |
725
|
|
|
|
|
|
|
|
726
|
|
|
|
|
|
|
Accessor for the original address found when parsing, or passed |
727
|
|
|
|
|
|
|
to C. |
728
|
|
|
|
|
|
|
|
729
|
|
|
|
|
|
|
=item host |
730
|
|
|
|
|
|
|
|
731
|
|
|
|
|
|
|
my $host = $address->host; |
732
|
|
|
|
|
|
|
|
733
|
|
|
|
|
|
|
Accessor for the host portion of an address's address. |
734
|
|
|
|
|
|
|
|
735
|
|
|
|
|
|
|
=item user |
736
|
|
|
|
|
|
|
|
737
|
|
|
|
|
|
|
my $user = $address->user; |
738
|
|
|
|
|
|
|
|
739
|
|
|
|
|
|
|
Accessor for the user portion of an address's address. |
740
|
|
|
|
|
|
|
|
741
|
|
|
|
|
|
|
=item format |
742
|
|
|
|
|
|
|
|
743
|
|
|
|
|
|
|
my $printable = $address->format; |
744
|
|
|
|
|
|
|
|
745
|
|
|
|
|
|
|
Returns a properly formatted RFC 2822 address representing the |
746
|
|
|
|
|
|
|
object. |
747
|
|
|
|
|
|
|
|
748
|
|
|
|
|
|
|
=item name |
749
|
|
|
|
|
|
|
|
750
|
|
|
|
|
|
|
my $name = $address->name; |
751
|
|
|
|
|
|
|
|
752
|
|
|
|
|
|
|
This method tries very hard to determine the name belonging to the address. |
753
|
|
|
|
|
|
|
First the C is checked. If that doesn't work out the C |
754
|
|
|
|
|
|
|
is looked into. If that still doesn't work out, the C portion of |
755
|
|
|
|
|
|
|
the C is returned. |
756
|
|
|
|
|
|
|
|
757
|
|
|
|
|
|
|
This method does B try to massage any name it identifies and instead |
758
|
|
|
|
|
|
|
leaves that up to someone else. Who is it to decide if someone wants their |
759
|
|
|
|
|
|
|
name capitalized, or if they're Irish? |
760
|
|
|
|
|
|
|
|
761
|
|
|
|
|
|
|
=back |
762
|
|
|
|
|
|
|
|
763
|
|
|
|
|
|
|
=head2 Overloaded Operators |
764
|
|
|
|
|
|
|
|
765
|
|
|
|
|
|
|
=over 4 |
766
|
|
|
|
|
|
|
|
767
|
|
|
|
|
|
|
=item stringify |
768
|
|
|
|
|
|
|
|
769
|
|
|
|
|
|
|
print "I have your email address, $address."; |
770
|
|
|
|
|
|
|
|
771
|
|
|
|
|
|
|
Objects stringify to C by default. It's possible that you don't |
772
|
|
|
|
|
|
|
like that idea. Okay, then, you can change it by modifying |
773
|
|
|
|
|
|
|
C<$Email:Address::STRINGIFY>. Please consider modifying this package |
774
|
|
|
|
|
|
|
variable using C. You might step on someone else's toes if you |
775
|
|
|
|
|
|
|
don't. |
776
|
|
|
|
|
|
|
|
777
|
|
|
|
|
|
|
{ |
778
|
|
|
|
|
|
|
local $Email::Address::STRINGIFY = 'host'; |
779
|
|
|
|
|
|
|
print "I have your address, $address."; |
780
|
|
|
|
|
|
|
# geeknest.com |
781
|
|
|
|
|
|
|
} |
782
|
|
|
|
|
|
|
print "I have your address, $address."; |
783
|
|
|
|
|
|
|
# "Casey West" |
784
|
|
|
|
|
|
|
|
785
|
|
|
|
|
|
|
Modifying this package variable is now deprecated. Subclassing is now the |
786
|
|
|
|
|
|
|
recommended approach. |
787
|
|
|
|
|
|
|
|
788
|
|
|
|
|
|
|
=back |
789
|
|
|
|
|
|
|
|
790
|
|
|
|
|
|
|
=head2 Did I Mention Fast? |
791
|
|
|
|
|
|
|
|
792
|
|
|
|
|
|
|
On his 1.8GHz Apple MacBook, rjbs gets these results: |
793
|
|
|
|
|
|
|
|
794
|
|
|
|
|
|
|
$ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 5 |
795
|
|
|
|
|
|
|
Rate Mail::Address Email::Address |
796
|
|
|
|
|
|
|
Mail::Address 2.59/s -- -44% |
797
|
|
|
|
|
|
|
Email::Address 4.59/s 77% -- |
798
|
|
|
|
|
|
|
|
799
|
|
|
|
|
|
|
$ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 25 |
800
|
|
|
|
|
|
|
Rate Mail::Address Email::Address |
801
|
|
|
|
|
|
|
Mail::Address 2.58/s -- -67% |
802
|
|
|
|
|
|
|
Email::Address 7.84/s 204% -- |
803
|
|
|
|
|
|
|
|
804
|
|
|
|
|
|
|
$ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 50 |
805
|
|
|
|
|
|
|
Rate Mail::Address Email::Address |
806
|
|
|
|
|
|
|
Mail::Address 2.57/s -- -70% |
807
|
|
|
|
|
|
|
Email::Address 8.53/s 232% -- |
808
|
|
|
|
|
|
|
|
809
|
|
|
|
|
|
|
...unfortunately, a known bug causes a loss of speed the string to parse has |
810
|
|
|
|
|
|
|
certain known characteristics, and disabling cache will also degrade |
811
|
|
|
|
|
|
|
performance. |
812
|
|
|
|
|
|
|
|
813
|
|
|
|
|
|
|
=head1 ACKNOWLEDGEMENTS |
814
|
|
|
|
|
|
|
|
815
|
|
|
|
|
|
|
Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying |
816
|
|
|
|
|
|
|
phrase-quoting bugs! |
817
|
|
|
|
|
|
|
|
818
|
|
|
|
|
|
|
=head1 AUTHORS |
819
|
|
|
|
|
|
|
|
820
|
|
|
|
|
|
|
=over 4 |
821
|
|
|
|
|
|
|
|
822
|
|
|
|
|
|
|
=item * |
823
|
|
|
|
|
|
|
|
824
|
|
|
|
|
|
|
Casey West |
825
|
|
|
|
|
|
|
|
826
|
|
|
|
|
|
|
=item * |
827
|
|
|
|
|
|
|
|
828
|
|
|
|
|
|
|
Ricardo SIGNES |
829
|
|
|
|
|
|
|
|
830
|
|
|
|
|
|
|
=back |
831
|
|
|
|
|
|
|
|
832
|
|
|
|
|
|
|
=head1 CONTRIBUTORS |
833
|
|
|
|
|
|
|
|
834
|
|
|
|
|
|
|
=for stopwords Alex Vandiver David Golden Steinbrunner Glenn Fowler Jim Brandt Kevin Falcone Pali Ruslan Zakirov sunnavy William Yardley |
835
|
|
|
|
|
|
|
|
836
|
|
|
|
|
|
|
=over 4 |
837
|
|
|
|
|
|
|
|
838
|
|
|
|
|
|
|
=item * |
839
|
|
|
|
|
|
|
|
840
|
|
|
|
|
|
|
Alex Vandiver |
841
|
|
|
|
|
|
|
|
842
|
|
|
|
|
|
|
=item * |
843
|
|
|
|
|
|
|
|
844
|
|
|
|
|
|
|
David Golden |
845
|
|
|
|
|
|
|
|
846
|
|
|
|
|
|
|
=item * |
847
|
|
|
|
|
|
|
|
848
|
|
|
|
|
|
|
David Steinbrunner |
849
|
|
|
|
|
|
|
|
850
|
|
|
|
|
|
|
=item * |
851
|
|
|
|
|
|
|
|
852
|
|
|
|
|
|
|
Glenn Fowler |
853
|
|
|
|
|
|
|
|
854
|
|
|
|
|
|
|
=item * |
855
|
|
|
|
|
|
|
|
856
|
|
|
|
|
|
|
Jim Brandt |
857
|
|
|
|
|
|
|
|
858
|
|
|
|
|
|
|
=item * |
859
|
|
|
|
|
|
|
|
860
|
|
|
|
|
|
|
Kevin Falcone |
861
|
|
|
|
|
|
|
|
862
|
|
|
|
|
|
|
=item * |
863
|
|
|
|
|
|
|
|
864
|
|
|
|
|
|
|
Pali |
865
|
|
|
|
|
|
|
|
866
|
|
|
|
|
|
|
=item * |
867
|
|
|
|
|
|
|
|
868
|
|
|
|
|
|
|
Ruslan Zakirov |
869
|
|
|
|
|
|
|
|
870
|
|
|
|
|
|
|
=item * |
871
|
|
|
|
|
|
|
|
872
|
|
|
|
|
|
|
sunnavy |
873
|
|
|
|
|
|
|
|
874
|
|
|
|
|
|
|
=item * |
875
|
|
|
|
|
|
|
|
876
|
|
|
|
|
|
|
William Yardley |
877
|
|
|
|
|
|
|
|
878
|
|
|
|
|
|
|
=back |
879
|
|
|
|
|
|
|
|
880
|
|
|
|
|
|
|
=head1 COPYRIGHT AND LICENSE |
881
|
|
|
|
|
|
|
|
882
|
|
|
|
|
|
|
This software is copyright (c) 2004 by Casey West. |
883
|
|
|
|
|
|
|
|
884
|
|
|
|
|
|
|
This is free software; you can redistribute it and/or modify it under |
885
|
|
|
|
|
|
|
the same terms as the Perl 5 programming language system itself. |
886
|
|
|
|
|
|
|
|
887
|
|
|
|
|
|
|
=cut |
888
|
|
|
|
|
|
|
|
889
|
|
|
|
|
|
|
__END__ |