view release on metacpan or  search on metacpan

lib/Email/Find.pm  view on Meta::CPAN

  use Email::Find;

  # new object oriented interface
  my $finder = Email::Find->new(\&callback);
  my $num_found - $finder->find(\$text);

  # good old functional style
  $num_found = find_emails($text, \&callback);

=head1 DESCRIPTION

Email::Find is a module for finding a I<subset> of RFC 822 email
addresses in arbitrary text (see L</"CAVEATS">).  The addresses it
finds are not guaranteed to exist or even actually be email addresses
at all (see L</"CAVEATS">), but they will be valid RFC 822 syntax.

Email::Find will perform some heuristics to avoid some of the more
obvious red herrings and false addresses, but there's only so much
which can be done without a human.

=head1 METHODS

=over 4

=item new

  $finder = Email::Find->new(\&callback);

Constructs new Email::Find object. Specified callback will be called
with each email as they're found.

=item find

  $num_emails_found = $finder->find(\$text);

Finds email addresses in the text and executes callback registered.

The callback is given two arguments.  The first is a Mail::Address
object representing the address found.  The second is the actual
original email as found in the text.  Whatever the callback returns
will replace the original text.

=head1 FUNCTIONS

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

=head1 EXAMPLES

  use Email::Find;

  # Simply print out all the addresses found leaving the text undisturbed.
  my $finder = Email::Find->new(sub {
				    my($email, $orig_email) = @_;
				    print "Found ".$email->format."\n";
				    return $orig_email;
				});
  $finder->find(\$text);

  # For each email found, ping its host to see if its alive.
  require Net::Ping;
  $ping = Net::Ping->new;
  my %Pinged = ();
  my $finder = Email::Find->new(sub {
  				    my($email, $orig_email) = @_;
  				    my $host = $email->host;
  				    next if exists $Pinged{$host};
  				    $Pinged{$host} = $ping->ping($host);
  				});

  $finder->find(\$text);

  while( my($host, $up) = each %Pinged ) {
      print "$host is ". $up ? 'up' : 'down' ."\n";
  }

  # Count how many addresses are found.
  my $finder = Email::Find->new(sub { $_[1] });
  print "Found ", $finder->find(\$text), " addresses\n";

  # Wrap each address in an HTML mailto link.
  my $finder = Email::Find->new(
      sub {
  	  my($email, $orig_email) = @_;
  	  my($address) = $email->format;
  	  return qq|<a href="mailto:$address">$orig_email</a>|;
      },
  );
  $finder->find(\$text);

=head1 SUBCLASSING

If you want to change the way this module works in finding email
address, you can do it by making your subclass of Email::Find, which
overrides C<addr_regex> and C<do_validate> method.

For example, the following class can additionally find email addresses
with dot before at mark. This is illegal in RFC822, see
L<Email::Valid::Loose> for details.

  package Email::Find::Loose;
  use base qw(Email::Find);
  use Email::Valid::Loose;

  # should return regex, which Email::Find will use in finding
  # strings which are "thought to be" email addresses
  sub addr_regex {
      return $Email::Valid::Loose::Addr_spec_re;
  }

  # should validate $addr is a valid email or not.
  # if so, return the address as a string.
  # else, return undef
  sub do_validate {
      my($self, $addr) = @_;
      return Email::Valid::Loose->address($addr);
  }

Let's see another example, which validates if the address is an
existent one or not, with Mail::CheckUser module.