.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" 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 3pm" .TH Email::Address 3pm "2023-01-14" "perl v5.36.0" "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 \- RFC 2822 Address Parsing and Creation .SH "VERSION" .IX Header "VERSION" version 1.913 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Email::Address; \& \& my @addresses = Email::Address\->parse($line); \& my $address = Email::Address\->new(Casey => \*(Aqcasey@localhost\*(Aq); \& \& print $address\->format; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This class implements a regex-based \s-1RFC 2822\s0 parser that locates email addresses in strings and returns a list of \f(CW\*(C`Email::Address\*(C'\fR objects found. Alternatively you may construct objects manually. The goal of this software is to be correct, and very very fast. .PP Version 1.909 and earlier of this module had vulnerabilies (\s-1CVE\-2015\-7686\s0 ) and (\s-1CVE\-2015\-12558\s0 ) which allowed specially constructed email to cause a denial of service. The reported vulnerabilities and some other pathalogical cases (meaning they really shouldn't occur in normal email) have been addressed in version 1.910 and newer. If you're running version 1.909 or older, you should update! .PP Alternatively, you could switch to \fBEmail::Address::XS\fR which has a backward compatible \s-1API.\s0 \fBWhy not just use that?\fR .SS "Package Variables" .IX Subsection "Package Variables" \&\fB\s-1ACHTUNG\s0!\fR Email isn't easy (if even possible) to parse with a regex, \fIat least\fR if you're on a \f(CW\*(C`perl\*(C'\fR prior to 5.10.0. Providing regular expressions for use by other programs isn't a great idea, because it makes it hard to improve the parser without breaking the \*(L"it's a regex\*(R" feature. Using these regular expressions is not encouraged, and methods like \f(CW\*(C`Email::Address\->is_addr_spec\*(C'\fR should be provided in the future. .PP Several regular expressions used in this package are useful to others. For convenience, these variables are declared as package variables that you may access from your program. .PP These regular expressions conform to the rules specified in \s-1RFC 2822.\s0 .PP You can access these variables using the full namespace. If you want short names, define them yourself. .PP .Vb 1 \& my $addr_spec = $Email::Address::addr_spec; .Ve .ie n .IP "$Email::Address::addr_spec" 4 .el .IP "\f(CW$Email::Address::addr_spec\fR" 4 .IX Item "$Email::Address::addr_spec" This regular expression defined what an email address is allowed to look like. .ie n .IP "$Email::Address::angle_addr" 4 .el .IP "\f(CW$Email::Address::angle_addr\fR" 4 .IX Item "$Email::Address::angle_addr" This regular expression defines an \f(CW$addr_spec\fR wrapped in angle brackets. .ie n .IP "$Email::Address::name_addr" 4 .el .IP "\f(CW$Email::Address::name_addr\fR" 4 .IX Item "$Email::Address::name_addr" This regular expression defines what an email address can look like with an optional preceding display name, also known as the \f(CW\*(C`phrase\*(C'\fR. .ie n .IP "$Email::Address::mailbox" 4 .el .IP "\f(CW$Email::Address::mailbox\fR" 4 .IX Item "$Email::Address::mailbox" This is the complete regular expression defining an \s-1RFC 2822\s0 email address with an optional preceding display name and optional following comment. .SS "Class Methods" .IX Subsection "Class Methods" .IP "parse" 4 .IX Item "parse" .Vb 3 \& my @addrs = Email::Address\->parse( \& q[me@local, Casey , "Casey" (West)] \& ); .Ve .Sp This method returns a list of \f(CW\*(C`Email::Address\*(C'\fR objects it finds in the input string. \fBPlease note\fR that it returns a list, and expects that it may find multiple addresses. The behavior in scalar context is undefined. .Sp The specification for an email address allows for infinitely nestable comments. That's nice in theory, but a little over done. By default this module allows for one (\f(CW1\fR) level of nested comments. If you think you need more, modify the \&\f(CW$Email::Address::COMMENT_NEST_LEVEL\fR package variable to allow more. .Sp .Vb 1 \& $Email::Address::COMMENT_NEST_LEVEL = 10; # I\*(Aqm deep .Ve .Sp The reason for this hardly-limiting limitation is simple: efficiency. .Sp Long strings of whitespace can be problematic for this module to parse, a bug which has not yet been adequately addressed. The default behavior is now to collapse multiple spaces into a single space, which avoids this problem. To prevent this behavior, set \f(CW$Email::Address::COLLAPSE_SPACES\fR to zero. This variable will go away when the bug is resolved properly. .Sp In accordance with \s-1RFC 822\s0 and its descendants, this module demands that email addresses be \s-1ASCII\s0 only. Any non-ASCII content in the parsed addresses will cause the parser to return no results. .IP "new" 4 .IX Item "new" .Vb 3 \& my $address = Email::Address\->new(undef, \*(Aqcasey@local\*(Aq); \& my $address = Email::Address\->new(\*(AqCasey West\*(Aq, \*(Aqcasey@local\*(Aq); \& my $address = Email::Address\->new(undef, \*(Aqcasey@local\*(Aq, \*(Aq(Casey)\*(Aq); .Ve .Sp Constructs and returns a new \f(CW\*(C`Email::Address\*(C'\fR object. Takes four positional arguments: phrase, email, and comment, and original string. .Sp The original string should only really be set using \f(CW\*(C`parse\*(C'\fR. .IP "purge_cache" 4 .IX Item "purge_cache" .Vb 1 \& Email::Address\->purge_cache; .Ve .Sp One way this module stays fast is with internal caches. Caches live in memory and there is the remote possibility that you will have a memory problem. On the off chance that you think you're one of those people, this class method will empty those caches. .Sp I've loaded over 12000 objects and not encountered a memory problem. .IP "disable_cache" 4 .IX Item "disable_cache" .PD 0 .IP "enable_cache" 4 .IX Item "enable_cache" .PD .Vb 1 \& Email::Address\->disable_cache if memory_low(); .Ve .Sp If you'd rather not cache address parses at all, you can disable (and re-enable) the Email::Address cache with these methods. The cache is enabled by default. .SS "Instance Methods" .IX Subsection "Instance Methods" .IP "phrase" 4 .IX Item "phrase" .Vb 2 \& my $phrase = $address\->phrase; \& $address\->phrase( "Me oh my" ); .Ve .Sp Accessor and mutator for the phrase portion of an address. .IP "address" 4 .IX Item "address" .Vb 2 \& my $addr = $address\->address; \& $addr\->address( "me@PROTECTED.com" ); .Ve .Sp Accessor and mutator for the address portion of an address. .IP "comment" 4 .IX Item "comment" .Vb 2 \& my $comment = $address\->comment; \& $address\->comment( "(Work address)" ); .Ve .Sp Accessor and mutator for the comment portion of an address. .IP "original" 4 .IX Item "original" .Vb 1 \& my $orig = $address\->original; .Ve .Sp Accessor for the original address found when parsing, or passed to \f(CW\*(C`new\*(C'\fR. .IP "host" 4 .IX Item "host" .Vb 1 \& my $host = $address\->host; .Ve .Sp Accessor for the host portion of an address's address. .IP "user" 4 .IX Item "user" .Vb 1 \& my $user = $address\->user; .Ve .Sp Accessor for the user portion of an address's address. .IP "format" 4 .IX Item "format" .Vb 1 \& my $printable = $address\->format; .Ve .Sp Returns a properly formatted \s-1RFC 2822\s0 address representing the object. .IP "name" 4 .IX Item "name" .Vb 1 \& my $name = $address\->name; .Ve .Sp This method tries very hard to determine the name belonging to the address. First the \f(CW\*(C`phrase\*(C'\fR is checked. If that doesn't work out the \f(CW\*(C`comment\*(C'\fR is looked into. If that still doesn't work out, the \f(CW\*(C`user\*(C'\fR portion of the \f(CW\*(C`address\*(C'\fR is returned. .Sp This method does \fBnot\fR try to massage any name it identifies and instead leaves that up to someone else. Who is it to decide if someone wants their name capitalized, or if they're Irish? .SS "Overloaded Operators" .IX Subsection "Overloaded Operators" .IP "stringify" 4 .IX Item "stringify" .Vb 1 \& print "I have your email address, $address."; .Ve .Sp Objects stringify to \f(CW\*(C`format\*(C'\fR by default. It's possible that you don't like that idea. Okay, then, you can change it by modifying \&\f(CW$Email:Address::STRINGIFY\fR. Please consider modifying this package variable using \f(CW\*(C`local\*(C'\fR. You might step on someone else's toes if you don't. .Sp .Vb 7 \& { \& local $Email::Address::STRINGIFY = \*(Aqhost\*(Aq; \& print "I have your address, $address."; \& # geeknest.com \& } \& print "I have your address, $address."; \& # "Casey West" .Ve .Sp Modifying this package variable is now deprecated. Subclassing is now the recommended approach. .SS "Did I Mention Fast?" .IX Subsection "Did I Mention Fast?" On his 1.8GHz Apple MacBook, rjbs gets these results: .PP .Vb 4 \& $ perl \-Ilib bench/ea\-vs\-ma.pl bench/corpus.txt 5 \& Rate Mail::Address Email::Address \& Mail::Address 2.59/s \-\- \-44% \& Email::Address 4.59/s 77% \-\- \& \& $ perl \-Ilib bench/ea\-vs\-ma.pl bench/corpus.txt 25 \& Rate Mail::Address Email::Address \& Mail::Address 2.58/s \-\- \-67% \& Email::Address 7.84/s 204% \-\- \& \& $ perl \-Ilib bench/ea\-vs\-ma.pl bench/corpus.txt 50 \& Rate Mail::Address Email::Address \& Mail::Address 2.57/s \-\- \-70% \& Email::Address 8.53/s 232% \-\- .Ve .PP \&...unfortunately, a known bug causes a loss of speed the string to parse has certain known characteristics, and disabling cache will also degrade performance. .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying phrase-quoting bugs! .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Casey West .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Alex Vandiver .IP "\(bu" 4 David Golden .IP "\(bu" 4 David Steinbrunner .IP "\(bu" 4 Glenn Fowler .IP "\(bu" 4 Jim Brandt .IP "\(bu" 4 Kevin Falcone .IP "\(bu" 4 Pali .IP "\(bu" 4 Ricardo Signes .IP "\(bu" 4 Ruslan Zakirov .IP "\(bu" 4 sunnavy .IP "\(bu" 4 William Yardley .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2004 by Casey West. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.