.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Email::Address::List 3pm" .TH Email::Address::List 3pm "2019-02-06" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Email::Address::List \- RFC close address list parsing .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Email::Address::List; \& \& my $header = <<\*(AqEND\*(Aq; \& Foo Bar , (an obsolete comment),,, \& a group: \& a . weird . address @ \& for\-real .biz \& ; invalid thingy, < \& more@example.com \& > \& END \& \& my @list = Email::Address::List\->parse($header); \& foreach my $e ( @list ) { \& if ($e\->{\*(Aqtype\*(Aq} eq \*(Aqmailbox\*(Aq) { \& print "an address: ", $e\->{\*(Aqvalue\*(Aq}\->format ,"\en"; \& } \& else { \& print $e\->{\*(Aqtype\*(Aq}, "\en" \& } \& } \& \& # prints: \& # an address: "Foo Bar" \& # comment \& # group start \& # an address: a.weird.address@forreal.biz \& # group end \& # unknown \& # an address: more@example.com .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Parser for From, To, Cc, Bcc, Reply-To, Sender and previous prefixed with Resent\- (eg Resent-From) headers. .SH "REASONING" .IX Header "REASONING" Email::Address is good at parsing addresses out of any text even mentioned headers and this module is derived work from Email::Address. .PP However, mentioned headers are structured and contain lists of addresses. Most of the time you want to parse such field from start to end keeping everything even if it's an invalid input. .SH "METHODS" .IX Header "METHODS" .SS "parse" .IX Subsection "parse" A class method that takes a header value (w/o name and :) and a set of named options, for example: .PP .Vb 1 \& my @list = Email::Address::List\->parse( $line, option => 1 ); .Ve .PP Returns list of hashes. Each hash at least has 'type' key that describes the entry. Types: .IP "mailbox" 4 .IX Item "mailbox" A mailbox entry with Email::Address object under value key. .Sp If mailbox has obsolete parts then 'obsolete' is true. .Sp If address (not display\-name/phrase or comments, but local\-part@domain) contains not \s-1ASCII\s0 chars then 'not_ascii' is set to true. According to \s-1RFC 5322\s0 not \s-1ASCII\s0 chars are not allowed within mailbox. However, there are no big problems if those are used and actually \s-1RFC 6532\s0 extends a few rules from 5322 with UTF8\-non\-ascii. Either use the feature or just skip such addresses with skip_not_ascii option. .IP "group start" 4 .IX Item "group start" Some headers with mailboxes may contain groupped addresses. This element is returned for position where group starts. Under value key you find name of the group. \fB\s-1NOTE\s0\fR that value is not post processed at the moment, so it may contain spaces, comments, quoted strings and other noise. Author willing to take patches and warns that this will be changed at some point without additional notifications, so if you need groups info then you better send a patch :) .Sp Groups can not be nested, but one field may have multiple groups or mix of addresses that are in a group and not in any. .Sp See skip_groups option. .IP "group end" 4 .IX Item "group end" Returned when a group ends. .IP "comment" 4 .IX Item "comment" Obsolete syntax allows one to use standalone comments between mailboxes that can not be addressed to any mailbox. In such situations a comment returned as an entry of this type. Comment itself is under value. .IP "unknown" 4 .IX Item "unknown" Returned if parser met something that shouldn't be there. Parser tries to recover by jumping over to next comma (or semicolon if inside group) that is out quoted string or comment, so \*(L"foo, bar, baz\*(R" string results in three unknown entries. Jumping over comments and quoted strings means that parser is very sensitive to unbalanced quotes and parens, but it's on purpose. .PP It can be controlled which elements are skipped, for example: .PP .Vb 1 \& Email::Address::List\->parse($line, skip_unknown => 1, ...); .Ve .IP "skip_comments" 4 .IX Item "skip_comments" Skips comments between mailboxes. Comments inside and next to a mailbox are not skipped, but returned as part of mailbox entry. .IP "skip_not_ascii" 4 .IX Item "skip_not_ascii" Skips mailboxes where address part has not \s-1ASCII\s0 characters. .IP "skip_groups" 4 .IX Item "skip_groups" Skips group starts and end elements, however emails within groups are still returned. .IP "skip_unknown" 4 .IX Item "skip_unknown" Skip anything that is not recognizable. It still tries to recover as described earlier. .SH "AUTHOR" .IX Header "AUTHOR" Ruslan Zakirov .SH "LICENSE" .IX Header "LICENSE" Under the same terms as Perl itself.