1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
=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 *
limitted 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.
example:
my $s = Mail::Message::Field::Full->parse($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
Mail::Address-E<gt>B<new>(PHRASE, ADDRESS, [ COMMENT ])
=over 4
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");
=back
$obj-E<gt>B<parse>(LINE)
=over 4
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
$obj-E<gt>B<address>
=over 4
Return the address part of the object.
=back
$obj-E<gt>B<comment>
=over 4
Return the comment part of the object
=back
$obj-E<gt>B<format>([ADDRESSes])
=over 4
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 with commas.
=back
$obj-E<gt>B<phrase>
=over 4
Return the phrase part of the object.
=back
=head2 Smart accessors
$obj-E<gt>B<host>
=over 4
Return the address excluding the user id and '@'
=back
$obj-E<gt>B<name>
=over 4
Using the information contained within the object attempt to identify what
the person or groups name is.
=back
$obj-E<gt>B<user>
=over 4
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-2007 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>
|
