{ "content": [ { "type": "text", "text": "# Email::Address (perldoc)\n\n## NAME\n\nEmail::Address - RFC 2822 Address Parsing and Creation\n\n## SYNOPSIS\n\nuse Email::Address;\nmy @addresses = Email::Address->parse($line);\nmy $address = Email::Address->new(Casey => 'casey@localhost');\nprint $address->format;\n\n## DESCRIPTION\n\nThis class implements a regex-based RFC 2822 parser that locates email addresses in strings and\nreturns a list of \"Email::Address\" objects found. Alternatively you may construct objects\nmanually. The goal of this software is to be correct, and very very fast.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION** (4 subsections)\n- **ACKNOWLEDGEMENTS**\n- **AUTHORS**\n- **CONTRIBUTORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Email::Address", "section": "", "mode": "perldoc", "summary": "Email::Address - RFC 2822 Address Parsing and Creation", "synopsis": "use Email::Address;\nmy @addresses = Email::Address->parse($line);\nmy $address = Email::Address->new(Casey => 'casey@localhost');\nprint $address->format;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 7, "subsections": [] }, { "name": "DESCRIPTION", "lines": 13, "subsections": [ { "name": "Package Variables", "lines": 30 }, { "name": "Class Methods", "lines": 54 }, { "name": "Instance Methods", "lines": 49 }, { "name": "Overloaded Operators", "lines": 39 } ] }, { "name": "ACKNOWLEDGEMENTS", "lines": 2, "subsections": [] }, { "name": "AUTHORS", "lines": 4, "subsections": [] }, { "name": "CONTRIBUTORS", "lines": 20, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "Email::Address - RFC 2822 Address Parsing and Creation\n", "subsections": [] }, "VERSION": { "content": "version 1.912\n", "subsections": [] }, "SYNOPSIS": { "content": "use Email::Address;\n\nmy @addresses = Email::Address->parse($line);\nmy $address = Email::Address->new(Casey => 'casey@localhost');\n\nprint $address->format;\n", "subsections": [] }, "DESCRIPTION": { "content": "This class implements a regex-based RFC 2822 parser that locates email addresses in strings and\nreturns a list of \"Email::Address\" objects found. Alternatively you may construct objects\nmanually. The goal of this software is to be correct, and very very fast.\n\nVersion 1.909 and earlier of this module had vulnerabilies (CVE-2015-7686\n) and (CVE-2015-12558\n) which allowed specially\nconstructed email to cause a denial of service. The reported vulnerabilities and some other\npathalogical cases (meaning they really shouldn't occur in normal email) have been addressed in\nversion 1.910 and newer. If you're running version 1.909 or older, you should update!\n\nAlternatively, you could switch to Email::Address::XS which has a backward compatible API.\n", "subsections": [ { "name": "Package Variables", "content": "ACHTUNG! Email isn't easy (if even possible) to parse with a regex, *at least* if you're on a\n\"perl\" prior to 5.10.0. Providing regular expressions for use by other programs isn't a great\nidea, because it makes it hard to improve the parser without breaking the \"it's a regex\"\nfeature. Using these regular expressions is not encouraged, and methods like\n\"Email::Address->isaddrspec\" should be provided in the future.\n\nSeveral regular expressions used in this package are useful to others. For convenience, these\nvariables are declared as package variables that you may access from your program.\n\nThese regular expressions conform to the rules specified in RFC 2822.\n\nYou can access these variables using the full namespace. If you want short names, define them\nyourself.\n\nmy $addrspec = $Email::Address::addrspec;\n\n$Email::Address::addrspec\nThis regular expression defined what an email address is allowed to look like.\n\n$Email::Address::angleaddr\nThis regular expression defines an $addrspec wrapped in angle brackets.\n\n$Email::Address::nameaddr\nThis regular expression defines what an email address can look like with an optional\npreceding display name, also known as the \"phrase\".\n\n$Email::Address::mailbox\nThis is the complete regular expression defining an RFC 2822 email address with an optional\npreceding display name and optional following comment.\n" }, { "name": "Class Methods", "content": "parse\nmy @addrs = Email::Address->parse(\nq[me@local, Casey , \"Casey\" (West)]\n);\n\nThis method returns a list of \"Email::Address\" objects it finds in the input string. Please\nnote that it returns a list, and expects that it may find multiple addresses. The behavior\nin scalar context is undefined.\n\nThe specification for an email address allows for infinitely nestable comments. That's nice\nin theory, but a little over done. By default this module allows for one (1) level of nested\ncomments. If you think you need more, modify the $Email::Address::COMMENTNESTLEVEL package\nvariable to allow more.\n\n$Email::Address::COMMENTNESTLEVEL = 10; # I'm deep\n\nThe reason for this hardly-limiting limitation is simple: efficiency.\n\nLong strings of whitespace can be problematic for this module to parse, a bug which has not\nyet been adequately addressed. The default behavior is now to collapse multiple spaces into\na single space, which avoids this problem. To prevent this behavior, set\n$Email::Address::COLLAPSESPACES to zero. This variable will go away when the bug is\nresolved properly.\n\nIn accordance with RFC 822 and its descendants, this module demands that email addresses be\nASCII only. Any non-ASCII content in the parsed addresses will cause the parser to return no\nresults.\n\nnew\nmy $address = Email::Address->new(undef, 'casey@local');\nmy $address = Email::Address->new('Casey West', 'casey@local');\nmy $address = Email::Address->new(undef, 'casey@local', '(Casey)');\n\nConstructs and returns a new \"Email::Address\" object. Takes four positional arguments:\nphrase, email, and comment, and original string.\n\nThe original string should only really be set using \"parse\".\n\npurgecache\nEmail::Address->purgecache;\n\nOne way this module stays fast is with internal caches. Caches live in memory and there is\nthe remote possibility that you will have a memory problem. On the off chance that you think\nyou're one of those people, this class method will empty those caches.\n\nI've loaded over 12000 objects and not encountered a memory problem.\n\ndisablecache\nenablecache\nEmail::Address->disablecache if memorylow();\n\nIf you'd rather not cache address parses at all, you can disable (and re-enable) the\nEmail::Address cache with these methods. The cache is enabled by default.\n" }, { "name": "Instance Methods", "content": "phrase\nmy $phrase = $address->phrase;\n$address->phrase( \"Me oh my\" );\n\nAccessor and mutator for the phrase portion of an address.\n\naddress\nmy $addr = $address->address;\n$addr->address( \"me@PROTECTED.com\" );\n\nAccessor and mutator for the address portion of an address.\n\ncomment\nmy $comment = $address->comment;\n$address->comment( \"(Work address)\" );\n\nAccessor and mutator for the comment portion of an address.\n\noriginal\nmy $orig = $address->original;\n\nAccessor for the original address found when parsing, or passed to \"new\".\n\nhost\nmy $host = $address->host;\n\nAccessor for the host portion of an address's address.\n\nuser\nmy $user = $address->user;\n\nAccessor for the user portion of an address's address.\n\nformat\nmy $printable = $address->format;\n\nReturns a properly formatted RFC 2822 address representing the object.\n\nname\nmy $name = $address->name;\n\nThis method tries very hard to determine the name belonging to the address. First the\n\"phrase\" is checked. If that doesn't work out the \"comment\" is looked into. If that still\ndoesn't work out, the \"user\" portion of the \"address\" is returned.\n\nThis method does not try to massage any name it identifies and instead leaves that up to\nsomeone else. Who is it to decide if someone wants their name capitalized, or if they're\nIrish?\n" }, { "name": "Overloaded Operators", "content": "stringify\nprint \"I have your email address, $address.\";\n\nObjects stringify to \"format\" by default. It's possible that you don't like that idea. Okay,\nthen, you can change it by modifying $Email:Address::STRINGIFY. Please consider modifying\nthis package variable using \"local\". You might step on someone else's toes if you don't.\n\n{\nlocal $Email::Address::STRINGIFY = 'host';\nprint \"I have your address, $address.\";\n# geeknest.com\n}\nprint \"I have your address, $address.\";\n# \"Casey West\" \n\nModifying this package variable is now deprecated. Subclassing is now the recommended\napproach.\n\nDid I Mention Fast?\nOn his 1.8GHz Apple MacBook, rjbs gets these results:\n\n$ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 5\nRate Mail::Address Email::Address\nMail::Address 2.59/s -- -44%\nEmail::Address 4.59/s 77% --\n\n$ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 25\nRate Mail::Address Email::Address\nMail::Address 2.58/s -- -67%\nEmail::Address 7.84/s 204% --\n\n$ perl -Ilib bench/ea-vs-ma.pl bench/corpus.txt 50\nRate Mail::Address Email::Address\nMail::Address 2.57/s -- -70%\nEmail::Address 8.53/s 232% --\n\n...unfortunately, a known bug causes a loss of speed the string to parse has certain known\ncharacteristics, and disabling cache will also degrade performance.\n" } ] }, "ACKNOWLEDGEMENTS": { "content": "Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying phrase-quoting bugs!\n", "subsections": [] }, "AUTHORS": { "content": "* Casey West\n\n* Ricardo SIGNES \n", "subsections": [] }, "CONTRIBUTORS": { "content": "* Alex Vandiver \n\n* David Golden \n\n* David Steinbrunner \n\n* Glenn Fowler \n\n* Jim Brandt \n\n* Kevin Falcone \n\n* Pali \n\n* Ruslan Zakirov \n\n* sunnavy \n\n* William Yardley \n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "This software is copyright (c) 2004 by Casey West.\n\nThis is free software; you can redistribute it and/or modify it under the same terms as the Perl\n5 programming language system itself.\n", "subsections": [] } } } }