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: Address.pm 881 2007-12-19 22:08:35Z rjbs@cpan.org $
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.
29 For convenience, these variables are declared as package variables that
30 you may access from your program.
31 These regular expressions conform to the rules specified in RFC 2822.
33 You can access these variables using the full namespace. If you want
35 short names, define them yourself.
36 my $addr_spec = $Email::Address::addr_spec;
38 $Email::Address::addr_spec
40 This regular expression defined what an email address is allowed to
41 look like.
42 $Email::Address::angle_addr
44 This regular expression defines an $addr_spec wrapped in angle
45 brackets.
46 $Email::Address::name_addr
48 This regular expression defines what an email address can look like
49 with an optional preceeding display name, also known as the
50 "phrase".
51 $Email::Address::mailbox
53 This is the complete regular expression defining an RFC 2822 emial
54 address with an optional preceeding display name and optional
55 following comment.
56 Class Methods
58 parse
59 my @addrs = Email::Address->parse(
60 q[me@local, Casey <me@local>, "Casey" <me@local> (West)]
61 );
62 This method returns a list of "Email::Address" objects it finds in
64 the input string.
65 The specification for an email address allows for infinitley
67 nestable comments. That's nice in theory, but a little over done.
68 By default this module allows for two (2) levels of nested
69 comments. If you think you need more, modify the
70 $Email::Address::COMMENT_NEST_LEVEL package variable to allow more.
71 $Email::Address::COMMENT_NEST_LEVEL = 10; # I'm deep
73 The reason for this hardly limiting limitation is simple:
75 efficiency.
76 Long strings of whitespace can be problematic for this module to
78 parse, a bug which has not yet been adequately addressed. The
79 default behavior is now to collapse multiple spaces into a single
80 space, which avoids this problem. To prevent this behavior, set
81 $Email::Address::COLLAPSE_SPACES to zero. This variable will go
82 away when the bug is resolved properly.
83 new
85 my $address = Email::Address->new(undef, 'casey@local');
86 my $address = Email::Address->new('Casey West', 'casey@local');
87 my $address = Email::Address->new(undef, 'casey@local', '(Casey)');
88 Constructs and returns a new "Email::Address" object. Takes four
90 positional arguments: phrase, email, and comment, and original
91 string.
92 The original string should only really be set using "parse".
94 purge_cache
96 Email::Address->purge_cache;
97 One way this module stays fast is with internal caches. Caches live
99 in memory and there is the remote possibility that you will have a
100 memory problem. In the off chance that you think you're one of
101 those people, this class method will empty those caches.
102 I've loaded over 12000 objects and not encountered a memory
104 problem.
105 disable_cache
107 enable_cache
108 Email::Address->disable_cache if memory_low();
109 If you'd rather not cache address parses at all, you can disable
111 (and reenable) the Email::Address cache with these methods. The
112 cache is enabled by default.
113 Instance Methods
115 phrase
116 my $phrase = $address->phrase;
117 $address->phrase( "Me oh my" );
118 Accessor and mutator for the phrase portion of an address.
120 address
122 my $addr = $address->address;
123 $addr->address( "me@PROTECTED.com" );
124 Accessor and mutator for the address portion of an address.
126 comment
128 my $comment = $address->comment;
129 $address->comment( "(Work address)" );
130 Accessor and mutator for the comment portion of an address.
132 original
134 my $orig = $address->original;
135 Accessor for the original address found when parsing, or passed to
137 "new".
138 host
140 my $host = $address->host;
141 Accessor for the host portion of an address's address.
143 user
145 my $user = $address->user;
146 Accessor for the user portion of an address's address.
148 format
150 my $printable = $address->format;
151 Returns a properly formatted RFC 2822 address representing the
153 object.
154 name
156 my $name = $address->name;
157 This method tries very hard to determine the name belonging to the
159 address. First the "phrase" is checked. If that doesn't work out
160 the "comment" is looked into. If that still doesn't work out, the
161 "user" portion of the "address" is returned.
162 This method does not try to massage any name it identifies and
164 instead leaves that up to someone else. Who is it to decide if
165 someone wants their name capitalized, or if they're Irish?
166 Overloaded Operators
168 stringify
169 print "I have your email address, $address.";
170 Objects stringify to "format" by default. It's possible that you
172 don't like that idea. Okay, then, you can change it by modifying
173 $Email:Address::STRINGIFY. Please consider modifying this package
174 variable using "local". You might step on someone else's toes if
175 you don't.
176 {
178 local $Email::Address::STRINGIFY = 'address';
179 print "I have your address, $address.";
180 # geeknest.com
181 }
182 print "I have your address, $address.";
183 # "Casey West" <casey@geeknest.com>
184 Did I Mention Fast?
186 On his 1.8GHz Apple MacBook, rjbs gets these results:
187 $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 5
189 Rate Mail::Address Email::Address
190 Mail::Address 2.59/s -- -44%
191 Email::Address 4.59/s 77% --
192 $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 25
194 Rate Mail::Address Email::Address
195 Mail::Address 2.58/s -- -67%
196 Email::Address 7.84/s 204% --
197 $ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 50
199 Rate Mail::Address Email::Address
200 Mail::Address 2.57/s -- -70%
201 Email::Address 8.53/s 232% --
202 ...unfortunately, a known bug causes a loss of speed the string to
204 parse has certain known characteristics, and disabling cache will also
205 degrade performance.
206
208 This module is maintained by the Perl Email Project
209 <http://emailproject.perl.org/wiki/Email::Address>
211
213 Email::Simple, perl.
214
216 Originally by Casey West, <casey@geeknest.com>.
217 Maintained, 2006-2007, Ricardo SIGNES <rjbs@cpan.org>.
219
221 Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying
222 phrase-quoting bugs!
223
225 Copyright (c) 2004 Casey West. All rights reserved. This module is
226 free software; you can redistribute it and/or modify it under the same
227 terms as Perl itself.
228perl v5.12.0 2007-12-19 Email::Address(3)