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

NAME

6       Email::Find - Find RFC 822 email addresses in plain text
7

SYNOPSIS

9         use Email::Find;
10
11         # new object oriented interface
12         my $finder = Email::Find->new(\&callback);
13         my $num_found - $finder->find(\$text);
14
15         # good old functional style
16         $num_found = find_emails($text, \&callback);
17

DESCRIPTION

19       Email::Find is a module for finding a subset of RFC 822 email addresses
20       in arbitrary text (see "CAVEATS").  The addresses it finds are not
21       guaranteed to exist or even actually be email addresses at all (see
22       "CAVEATS"), but they will be valid RFC 822 syntax.
23
24       Email::Find will perform some heuristics to avoid some of the more
25       obvious red herrings and false addresses, but there's only so much
26       which can be done without a human.
27

METHODS

29       new
30             $finder = Email::Find->new(\&callback);
31
32           Constructs new Email::Find object. Specified callback will be
33           called with each email as they're found.
34
35       find
36             $num_emails_found = $finder->find(\$text);
37
38           Finds email addresses in the text and executes callback registered.
39
40           The callback is given two arguments.  The first is a Mail::Address
41           object representing the address found.  The second is the actual
42           original email as found in the text.  Whatever the callback returns
43           will replace the original text.
44

FUNCTIONS

46       For backward compatibility, Email::Find exports one function,
47       find_emails(). It works very similar to URI::Find's find_uris().
48

EXAMPLES

50         use Email::Find;
51
52         # Simply print out all the addresses found leaving the text undisturbed.
53         my $finder = Email::Find->new(sub {
54                                           my($email, $orig_email) = @_;
55                                           print "Found ".$email->format."\n";
56                                           return $orig_email;
57                                       });
58         $finder->find(\$text);
59
60         # For each email found, ping its host to see if its alive.
61         require Net::Ping;
62         $ping = Net::Ping->new;
63         my %Pinged = ();
64         my $finder = Email::Find->new(sub {
65                                           my($email, $orig_email) = @_;
66                                           my $host = $email->host;
67                                           next if exists $Pinged{$host};
68                                           $Pinged{$host} = $ping->ping($host);
69                                       });
70
71         $finder->find(\$text);
72
73         while( my($host, $up) = each %Pinged ) {
74             print "$host is ". $up ? 'up' : 'down' ."\n";
75         }
76
77         # Count how many addresses are found.
78         my $finder = Email::Find->new(sub { $_[1] });
79         print "Found ", $finder->find(\$text), " addresses\n";
80
81         # Wrap each address in an HTML mailto link.
82         my $finder = Email::Find->new(
83             sub {
84                 my($email, $orig_email) = @_;
85                 my($address) = $email->format;
86                 return qq|<a href="mailto:$address">$orig_email</a>|;
87             },
88         );
89         $finder->find(\$text);
90

SUBCLASSING

92       If you want to change the way this module works in finding email
93       address, you can do it by making your subclass of Email::Find, which
94       overrides "addr_regex" and "do_validate" method.
95
96       For example, the following class can additionally find email addresses
97       with dot before at mark. This is illegal in RFC822, see
98       Email::Valid::Loose for details.
99
100         package Email::Find::Loose;
101         use base qw(Email::Find);
102         use Email::Valid::Loose;
103
104         # should return regex, which Email::Find will use in finding
105         # strings which are "thought to be" email addresses
106         sub addr_regex {
107             return $Email::Valid::Loose::Addr_spec_re;
108         }
109
110         # should validate $addr is a valid email or not.
111         # if so, return the address as a string.
112         # else, return undef
113         sub do_validate {
114             my($self, $addr) = @_;
115             return Email::Valid::Loose->address($addr);
116         }
117
118       Let's see another example, which validates if the address is an
119       existent one or not, with Mail::CheckUser module.
120
121         package Email::Find::Existent;
122         use base qw(Email::Find);
123         use Mail::CheckUser qw(check_email);
124
125         sub do_validate {
126             my($self, $addr) = @_;
127             return check_email($addr) ? $addr : undef;
128         }
129

CAVEATS

131       Why a subset of RFC 822?
132           I say that this module finds a subset of RFC 822 because if I
133           attempted to look for all possible valid RFC 822 addresses I'd wind
134           up practically matching the entire block of text!  The complete
135           specification is so wide open that its difficult to construct
136           soemthing that's not an RFC 822 address.
137
138           To keep myself sane, I look for the 'address spec' or 'global
139           address' part of an RFC 822 address.  This is the part which most
140           people consider to be an email address (the 'foo@bar.com' part) and
141           it is also the part which contains the information necessary for
142           delivery.
143
144       Why are some of the matches not email addresses?
145           Alas, many things which aren't email addresses look like email
146           addresses and parse just fine as them.  The biggest headache is
147           email and usenet and email message IDs.  I do my best to avoid
148           them, but there's only so much cleverness you can pack into one
149           library.
150

AUTHORS

152       Copyright 2000, 2001 Michael G Schwern <schwern@pobox.com>.  All rights
153       reserved.
154
155       Current maintainer is Tatsuhiko Miyagawa <miyagawa@bulknews.net>.
156

THANKS

158       Schwern thanks to Jeremy Howard for his patch to make it work under
159       5.005.
160

LICENSE

162       This module is free software; you may redistribute it and/or modify it
163       under the same terms as Perl itself.
164
165       The author STRONGLY SUGGESTS that this module not be used for the
166       purposes of sending unsolicited email (ie. spamming) in any way, shape
167       or form or for the purposes of generating lists for commercial sale.
168
169       If you use this module for spamming I reserve the right to make fun of
170       you.
171

SEE ALSO

173       Email::Valid, RFC 822, URI::Find, Apache::AntiSpam, Email::Valid::Loose
174

POD ERRORS

176       Hey! The above document had some coding errors, which are explained
177       below:
178
179       Around line 138:
180           You forgot a '=back' before '=head1'
181
182
183
184perl v5.12.0                      2007-01-16                    Email::Find(3)
Impressum