1Email::Address::List(3)User Contributed Perl DocumentatioEnmail::Address::List(3)
2
3
4

NAME

6       Email::Address::List - RFC close address list parsing
7

SYNOPSIS

9           use Email::Address::List;
10
11           my $header = <<'END';
12           Foo Bar <simple@example.com>, (an obsolete comment),,,
13            a group:
14             a . weird . address @
15             for-real .biz
16            ; invalid thingy, <
17            more@example.com
18            >
19           END
20
21           my @list = Email::Address::List->parse($header);
22           foreach my $e ( @list ) {
23               if ($e->{'type'} eq 'mailbox') {
24                   print "an address: ", $e->{'value'}->format ,"\n";
25               }
26               else {
27                   print $e->{'type'}, "\n"
28               }
29           }
30
31           # prints:
32           # an address: "Foo Bar" <simple@example.com>
33           # comment
34           # group start
35           # an address: a.weird.address@forreal.biz
36           # group end
37           # unknown
38           # an address: more@example.com
39

DESCRIPTION

41       Parser for From, To, Cc, Bcc, Reply-To, Sender and previous prefixed
42       with Resent- (eg Resent-From) headers.
43

REASONING

45       Email::Address is good at parsing addresses out of any text even
46       mentioned headers and this module is derived work from Email::Address.
47
48       However, mentioned headers are structured and contain lists of
49       addresses. Most of the time you want to parse such field from start to
50       end keeping everything even if it's an invalid input.
51

METHODS

53   parse
54       A class method that takes a header value (w/o name and :) and a set of
55       named options, for example:
56
57           my @list = Email::Address::List->parse( $line, option => 1 );
58
59       Returns list of hashes. Each hash at least has 'type' key that
60       describes the entry. Types:
61
62       mailbox
63           A mailbox entry with Email::Address object under value key.
64
65           If mailbox has obsolete parts then 'obsolete' is true.
66
67           If address (not display-name/phrase or comments, but
68           local-part@domain) contains not ASCII chars then 'not_ascii' is set
69           to true. According to RFC 5322 not ASCII chars are not allowed
70           within mailbox. However, there are no big problems if those are
71           used and actually RFC 6532 extends a few rules from 5322 with
72           UTF8-non-ascii. Either use the feature or just skip such addresses
73           with skip_not_ascii option.
74
75       group start
76           Some headers with mailboxes may contain groupped addresses. This
77           element is returned for position where group starts. Under value
78           key you find name of the group. NOTE that value is not post
79           processed at the moment, so it may contain spaces, comments, quoted
80           strings and other noise. Author willing to take patches and warns
81           that this will be changed at some point without additional
82           notifications, so if you need groups info then you better send a
83           patch :)
84
85           Groups can not be nested, but one field may have multiple groups or
86           mix of addresses that are in a group and not in any.
87
88           See skip_groups option.
89
90       group end
91           Returned when a group ends.
92
93       comment
94           Obsolete syntax allows one to use standalone comments between
95           mailboxes that can not be addressed to any mailbox. In such
96           situations a comment returned as an entry of this type. Comment
97           itself is under value.
98
99       unknown
100           Returned if parser met something that shouldn't be there. Parser
101           tries to recover by jumping over to next comma (or semicolon if
102           inside group) that is out quoted string or comment, so "foo, bar,
103           baz" string results in three unknown entries. Jumping over comments
104           and quoted strings means that parser is very sensitive to
105           unbalanced quotes and parens, but it's on purpose.
106
107       It can be controlled which elements are skipped, for example:
108
109           Email::Address::List->parse($line, skip_unknown => 1, ...);
110
111       skip_comments
112           Skips comments between mailboxes. Comments inside and next to a
113           mailbox are not skipped, but returned as part of mailbox entry.
114
115       skip_not_ascii
116           Skips mailboxes where address part has not ASCII characters.
117
118       skip_groups
119           Skips group starts and end elements, however emails within groups
120           are still returned.
121
122       skip_unknown
123           Skip anything that is not recognizable. It still tries to recover
124           as described earlier.
125

AUTHOR

127       Ruslan Zakirov <ruz@bestpractical.com>
128

LICENSE

130       Under the same terms as Perl itself.
131
132
133
134perl v5.36.0                      2022-07-22           Email::Address::List(3)
Impressum