README
1NAME
2 Email::Address::List - RFC close address list parsing
3
4SYNOPSIS
5 use Email::Address::List;
6
7 my $header = <<'END';
8 Foo Bar <simple@example.com>, (an obsolete comment),,,
9 a group:
10 a . weird . address @
11 for-real .biz
12 ; invalid thingy, <
13 more@example.com
14 >
15 END
16
17 my @list = Email::Address::List->parse($header);
18 foreach my $e ( @list ) {
19 if ($e->{'type'} eq 'mailbox') {
20 print "an address: ", $e->{'value'}->format ,"\n";
21 }
22 else {
23 print $e->{'type'}, "\n"
24 }
25 }
26
27 # prints:
28 # an address: "Foo Bar" <simple@example.com>
29 # comment
30 # group start
31 # an address: a.weird.address@forreal.biz
32 # group end
33 # unknown
34 # an address: more@example.com
35
36DESCRIPTION
37 Parser for From, To, Cc, Bcc, Reply-To, Sender and previous prefixed
38 with Resent- (eg Resent-From) headers.
39
40REASONING
41 Email::Address is good at parsing addresses out of any text even
42 mentioned headers and this module is derived work from Email::Address.
43
44 However, mentioned headers are structured and contain lists of
45 addresses. Most of the time you want to parse such field from start to
46 end keeping everything even if it's an invalid input.
47
48METHODS
49 parse
50 A class method that takes a header value (w/o name and :) and a set of
51 named options, for example:
52
53 my @list = Email::Address::List->parse( $line, option => 1 );
54
55 Returns list of hashes. Each hash at least has 'type' key that describes
56 the entry. Types:
57
58 mailbox
59 A mailbox entry with Email::Address object under value key.
60
61 If mailbox has obsolete parts then 'obsolete' is true.
62
63 If address (not display-name/phrase or comments, but
64 local-part@domain) contains not ASCII chars then 'not_ascii' is set
65 to true. According to RFC 5322 not ASCII chars are not allowed
66 within mailbox. However, there are no big problems if those are used
67 and actually RFC 6532 extends a few rules from 5322 with
68 UTF8-non-ascii. Either use the feature or just skip such addresses
69 with skip_not_ascii option.
70
71 group start
72 Some headers with mailboxes may contain groupped addresses. This
73 element is returned for position where group starts. Under value key
74 you find name of the group. NOTE that value is not post processed at
75 the moment, so it may contain spaces, comments, quoted strings and
76 other noise. Author willing to take patches and warns that this will
77 be changed at some point without additional notifications, so if you
78 need groups info then you better send a patch :)
79
80 Groups can not be nested, but one field may have multiple groups or
81 mix of addresses that are in a group and not in any.
82
83 See skip_groups option.
84
85 group end
86 Returned when a group ends.
87
88 comment
89 Obsolete syntax allows one to use standalone comments between
90 mailboxes that can not be addressed to any mailbox. In such
91 situations a comment returned as an entry of this type. Comment
92 itself is under value.
93
94 unknown
95 Returned if parser met something that shouldn't be there. Parser
96 tries to recover by jumping over to next comma (or semicolon if
97 inside group) that is out quoted string or comment, so "foo, bar,
98 baz" string results in three unknown entries. Jumping over comments
99 and quoted strings means that parser is very sensitive to unbalanced
100 quotes and parens, but it's on purpose.
101
102 It can be controlled which elements are skipped, for example:
103
104 Email::Address::List->parse($line, skip_unknown => 1, ...);
105
106 skip_comments
107 Skips comments between mailboxes. Comments inside and next to a
108 mailbox are not skipped, but returned as part of mailbox entry.
109
110 skip_not_ascii
111 Skips mailboxes where address part has not ASCII characters.
112
113 skip_groups
114 Skips group starts and end elements, however emails within groups
115 are still returned.
116
117 skip_unknown
118 Skip anything that is not recognizable. It still tries to recover as
119 described earlier.
120
121AUTHOR
122 Ruslan Zakirov <ruz@bestpractical.com>
123
124LICENSE
125 Under the same terms as Perl itself.
126
127