165 lines
4.1 KiB
Plaintext
165 lines
4.1 KiB
Plaintext
=encoding utf8
|
|
|
|
=head1 NAME
|
|
|
|
Mail::Address - parse mail addresses
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
use Mail::Address;
|
|
my @addrs = Mail::Address->parse($line);
|
|
|
|
foreach $addr (@addrs) {
|
|
print $addr->format,"\n";
|
|
}
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
C<Mail::Address> extracts and manipulates email addresses from a message
|
|
header. It cannot be used to extract addresses from some random text.
|
|
You can use this module to create RFC822 compliant fields.
|
|
|
|
Although C<Mail::Address> is a very popular subject for books, and is
|
|
used in many applications, it does a very poor job on the more complex
|
|
message fields. It does only handle simple address formats (which
|
|
covers about 95% of what can be found). Problems are with
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
no support for address groups, even not with the semi-colon as
|
|
separator between addresses;
|
|
|
|
=item *
|
|
|
|
limited support for escapes in phrases and comments. There are
|
|
cases where it can get wrong; and
|
|
|
|
=item *
|
|
|
|
you have to take care of most escaping when you create an address yourself:
|
|
C<Mail::Address> does not do that for you.
|
|
|
|
=back
|
|
|
|
Often requests are made to the maintainers of this code improve this
|
|
situation, but this is not a good idea, where it will break zillions
|
|
of existing applications. If you wish for a fully RFC2822 compliant
|
|
implementation you may take a look at L<Mail::Message::Field::Full>,
|
|
part of MailBox.
|
|
|
|
B<. Example>
|
|
|
|
my $s = Mail::Message::Field::Full->new($from_header);
|
|
# ref $s isa Mail::Message::Field::Addresses;
|
|
|
|
my @g = $s->groups; # all groups, at least one
|
|
# ref $g[0] isa Mail::Message::Field::AddrGroup;
|
|
my $ga = $g[0]->addresses; # group addresses
|
|
|
|
my @a = $s->addresses; # all addresses
|
|
# ref $a[0] isa Mail::Message::Field::Address;
|
|
|
|
=head1 METHODS
|
|
|
|
=head2 Constructors
|
|
|
|
=over 4
|
|
|
|
=item Mail::Address-E<gt>B<new>( $phrase, $address, [ $comment ] )
|
|
|
|
Create a new C<Mail::Address> object which represents an address with the
|
|
elements given. In a message these 3 elements would be seen like:
|
|
|
|
PHRASE <ADDRESS> (COMMENT)
|
|
ADDRESS (COMMENT)
|
|
|
|
example:
|
|
|
|
Mail::Address->new("Perl5 Porters", "perl5-porters@africa.nicoh.com");
|
|
|
|
=item $obj-E<gt>B<parse>($line)
|
|
|
|
Parse the given line a return a list of extracted C<Mail::Address> objects.
|
|
The line would normally be one taken from a To,Cc or Bcc line in a message
|
|
|
|
example:
|
|
|
|
my @addr = Mail::Address->parse($line);
|
|
|
|
=back
|
|
|
|
=head2 Accessors
|
|
|
|
=over 4
|
|
|
|
=item $obj-E<gt>B<address>()
|
|
|
|
Return the address part of the object.
|
|
|
|
=item $obj-E<gt>B<comment>()
|
|
|
|
Return the comment part of the object
|
|
|
|
=item $obj-E<gt>B<format>(@addresses)
|
|
|
|
Return a string representing the address in a suitable form to be placed
|
|
on a C<To>, C<Cc>, or C<Bcc> line of a message. This method is called on
|
|
the first address to be used; other specified addresses will be appended,
|
|
separated by commas.
|
|
|
|
=item $obj-E<gt>B<phrase>()
|
|
|
|
Return the phrase part of the object.
|
|
|
|
=back
|
|
|
|
=head2 Smart accessors
|
|
|
|
=over 4
|
|
|
|
=item $obj-E<gt>B<host>()
|
|
|
|
Return the address excluding the user id and '@'
|
|
|
|
=item $obj-E<gt>B<name>()
|
|
|
|
Using the information contained within the object attempt to identify what
|
|
the person or groups name is.
|
|
|
|
B<Note:> This function tries to be smart with the "phrase" of the
|
|
email address, which is probably a very bad idea. Consider to use
|
|
L<phrase()|Mail::Address/"Accessors"> itself.
|
|
|
|
=item $obj-E<gt>B<user>()
|
|
|
|
Return the address excluding the '@' and the mail domain
|
|
|
|
=back
|
|
|
|
=head1 SEE ALSO
|
|
|
|
This module is part of the MailTools distribution,
|
|
F<http://perl.overmeer.net/mailtools/>.
|
|
|
|
=head1 AUTHORS
|
|
|
|
The MailTools bundle was developed by Graham Barr. Later, Mark
|
|
Overmeer took over maintenance without commitment to further development.
|
|
|
|
Mail::Cap by Gisle Aas E<lt>aas@oslonett.noE<gt>.
|
|
Mail::Field::AddrList by Peter Orbaek E<lt>poe@cit.dkE<gt>.
|
|
Mail::Mailer and Mail::Send by Tim Bunce E<lt>Tim.Bunce@ig.co.ukE<gt>.
|
|
For other contributors see ChangeLog.
|
|
|
|
=head1 LICENSE
|
|
|
|
Copyrights 1995-2000 Graham Barr E<lt>gbarr@pobox.comE<gt> and
|
|
2001-2017 Mark Overmeer E<lt>perl@overmeer.netE<gt>.
|
|
|
|
This program is free software; you can redistribute it and/or modify it
|
|
under the same terms as Perl itself.
|
|
See F<http://www.perl.com/perl/misc/Artistic.html>
|
|
|