{
    "mode": "perldoc",
    "parameter": "Email::Address::XS",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Email%3A%3AAddress%3A%3AXS/json",
    "generated": "2026-06-11T11:37:04Z",
    "synopsis": "use Email::Address::XS;\nmy $winstonsaddress = Email::Address::XS->new(phrase => 'Winston Smith', user => 'winston.smith', host => 'recdep.minitrue', comment => 'Records Department');\nprint $winstonsaddress->address();\n# winston.smith@recdep.minitrue\nmy $juliasaddress = Email::Address::XS->new('Julia', 'julia@ficdep.minitrue');\nprint $juliasaddress->format();\n# Julia <julia@ficdep.minitrue>\nmy $usersaddress = Email::Address::XS->parse('user <user@oceania>');\nprint $usersaddress->host();\n# oceania\nmy $goldsteinsaddress = Email::Address::XS->parsebareaddress('goldstein@brotherhood.oceania');\nprint $goldsteinsaddress->user();\n# goldstein\nmy @addresses = Email::Address::XS->parse('\"Winston Smith\" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>');\n# ($winstonsaddress, $juliasaddress)\nuse Email::Address::XS qw(formatemailaddresses formatemailgroups parseemailaddresses parseemailgroups);\nmy $addressesstring = formatemailaddresses($winstonsaddress, $juliasaddress, $usersaddress);\n# \"Winston Smith\" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>, user <user@oceania>\nmy @addresses = map { $->address() } parseemailaddresses($addressesstring);\n# ('winston.smith@recdep.minitrue', 'julia@ficdep.minitrue', 'user@oceania')\nmy $groupsstring = formatemailgroups('Brotherhood' => [ $winstonsaddress, $juliasaddress ], undef() => [ $usersaddress ]);\n# Brotherhood: \"Winston Smith\" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>;, user <user@oceania>\nmy @groups = parseemailgroups($groupsstring);\n# ('Brotherhood' => [ $winstonsaddress, $juliasaddress ], undef() => [ $usersaddress ])\nuse Email::Address::XS qw(composeaddress splitaddress);\nmy ($user, $host) = splitaddress('julia(outer party)@ficdep.minitrue');\n# ('julia', 'ficdep.minitrue')\nmy $string = composeaddress('charrington\"@\"shop', 'thought.police.oceania');\n# \"charrington\\\"@\\\"shop\"@thought.police.oceania",
    "sections": {
        "NAME": {
            "content": "Email::Address::XS - Parse and format RFC 5322 email addresses and groups\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Email::Address::XS;\n\nmy $winstonsaddress = Email::Address::XS->new(phrase => 'Winston Smith', user => 'winston.smith', host => 'recdep.minitrue', comment => 'Records Department');\nprint $winstonsaddress->address();\n# winston.smith@recdep.minitrue\n\nmy $juliasaddress = Email::Address::XS->new('Julia', 'julia@ficdep.minitrue');\nprint $juliasaddress->format();\n# Julia <julia@ficdep.minitrue>\n\nmy $usersaddress = Email::Address::XS->parse('user <user@oceania>');\nprint $usersaddress->host();\n# oceania\n\nmy $goldsteinsaddress = Email::Address::XS->parsebareaddress('goldstein@brotherhood.oceania');\nprint $goldsteinsaddress->user();\n# goldstein\n\nmy @addresses = Email::Address::XS->parse('\"Winston Smith\" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>');\n# ($winstonsaddress, $juliasaddress)\n\n\nuse Email::Address::XS qw(formatemailaddresses formatemailgroups parseemailaddresses parseemailgroups);\n\nmy $addressesstring = formatemailaddresses($winstonsaddress, $juliasaddress, $usersaddress);\n# \"Winston Smith\" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>, user <user@oceania>\n\nmy @addresses = map { $->address() } parseemailaddresses($addressesstring);\n# ('winston.smith@recdep.minitrue', 'julia@ficdep.minitrue', 'user@oceania')\n\nmy $groupsstring = formatemailgroups('Brotherhood' => [ $winstonsaddress, $juliasaddress ], undef() => [ $usersaddress ]);\n# Brotherhood: \"Winston Smith\" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>;, user <user@oceania>\n\nmy @groups = parseemailgroups($groupsstring);\n# ('Brotherhood' => [ $winstonsaddress, $juliasaddress ], undef() => [ $usersaddress ])\n\n\nuse Email::Address::XS qw(composeaddress splitaddress);\n\nmy ($user, $host) = splitaddress('julia(outer party)@ficdep.minitrue');\n# ('julia', 'ficdep.minitrue')\n\nmy $string = composeaddress('charrington\"@\"shop', 'thought.police.oceania');\n# \"charrington\\\"@\\\"shop\"@thought.police.oceania\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This module implements RFC 5322 <https://tools.ietf.org/html/rfc5322> parser and formatter of\nemail addresses and groups. It parses an input string from email headers which contain a list of\nemail addresses or a groups of email addresses (like From, To, Cc, Bcc, Reply-To, Sender, ...).\nAlso it can generate a string value for those headers from a list of email addresses objects.\nModule is backward compatible with RFC 2822 <https://tools.ietf.org/html/rfc2822> and RFC 822\n<https://tools.ietf.org/html/rfc822>.\n\nParser and formatter functionality is implemented in XS and uses shared code from Dovecot IMAP\nserver.\n\nIt is a drop-in replacement for the Email::Address module which has several security issues.\nE.g. issue CVE-2015-7686 (Algorithmic complexity vulnerability)\n<https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-7686>, which allows remote attackers to\ncause denial of service, is still present in Email::Address version 1.908.\n\nEmail::Address::XS module was created to finally fix CVE-2015-7686.\n\nExisting applications that use Email::Address module could be easily switched to\nEmail::Address::XS module. In most cases only changing \"use Email::Address\" to \"use\nEmail::Address::XS\" and replacing every \"Email::Address\" occurrence with \"Email::Address::XS\" is\nsufficient.\n\nSo unlike Email::Address, this module does not use regular expressions for parsing but instead\nnative XS implementation parses input string sequentially according to RFC 5322 grammar.\n\nAdditionally it has support also for named groups and so can be use instead of the\nEmail::Address::List module.\n\nIf you are looking for the module which provides object representation for the list of email\naddresses suitable for the MIME email headers, see Email::MIME::Header::AddressList.\n\nEXPORT\nNone by default. Exportable functions are: \"parseemailaddresses\", \"parseemailgroups\",\n\"formatemailaddresses\", \"formatemailgroups\", \"composeaddress\", \"splitaddress\".\n",
            "subsections": [
                {
                    "name": "Exportable Functions",
                    "content": "formatemailaddresses\nuse Email::Address::XS qw(formatemailaddresses);\n\nmy $winstonsaddress = Email::Address::XS->new(phrase => 'Winston Smith', address => 'winston@recdep.minitrue');\nmy $juliasaddress = Email::Address::XS->new(phrase => 'Julia', address => 'julia@ficdep.minitrue');\nmy @addresses = ($winstonsaddress, $juliasaddress);\nmy $string = formatemailaddresses(@addresses);\nprint $string;\n# \"Winston Smith\" <winston@recdep.minitrue>, Julia <julia@ficdep.minitrue>\n\nTakes a list of email address objects and returns one formatted string of those email\naddresses.\n\nformatemailgroups\nuse Email::Address::XS qw(formatemailgroups);\n\nmy $winstonsaddress = Email::Address::XS->new(phrase => 'Winston Smith', user => 'winston.smith', host => 'recdep.minitrue');\nmy $juliasaddress = Email::Address::XS->new('Julia', 'julia@ficdep.minitrue');\nmy $usersaddress = Email::Address::XS->new(address => 'user@oceania');\n\nmy $groupsstring = formatemailgroups('Brotherhood' => [ $winstonsaddress, $juliasaddress ], undef() => [ $usersaddress ]);\nprint $groupsstring;\n# Brotherhood: \"Winston Smith\" <winston.smith@recdep.minitrue>, Julia <julia@ficdep.minitrue>;, user@oceania\n\nmy $undisclosedstring = formatemailgroups('undisclosed-recipients' => []);\nprint $undisclosedstring;\n# undisclosed-recipients:;\n\nLike \"formatemailaddresses\" but this method takes pairs which consist of a group display\nname and a reference to address list. If a group is not undef then address list is formatted\ninside named group.\n\nparseemailaddresses\nuse Email::Address::XS qw(parseemailaddresses);\n\nmy $string = '\"Winston Smith\" <winston.smith@recdep.minitrue>, Julia <julia@ficdep.minitrue>, user@oceania';\nmy @addresses = parseemailaddresses($string);\n# @addresses now contains three Email::Address::XS objects, one for each address\n\nParses an input string and returns a list of Email::Address::XS objects. Optional second\nstring argument specifies class name for blessing new objects.\n\nparseemailgroups\nuse Email::Address::XS qw(parseemailgroups);\n\nmy $string = 'Brotherhood: \"Winston Smith\" <winston.smith@recdep.minitrue>, Julia <julia@ficdep.minitrue>;, user@oceania, undisclosed-recipients:;';\nmy @groups = parseemailgroups($string);\n# @groups now contains list ('Brotherhood' => [ $winstonsobject, $juliasobject ], undef() => [ $usersobject ], 'undisclosed-recipients' => [])\n\nLike \"parseemailaddresses\" but this function returns a list of pairs: a group display name\nand a reference to a list of addresses which belongs to that named group. An undef value for\na group means that a following list of addresses is not inside any named group. An output is\nin a same format as a input for the function \"formatemailgroups\". This function preserves\norder of groups and does not do any de-duplication or merging.\n\ncomposeaddress\nuse Email::Address::XS qw(composeaddress);\nmy $stringaddress = composeaddress($user, $host);\n\nTakes an unescaped user part and unescaped host part of an address and returns escaped\naddress.\n\nAvailable since version 1.01.\n\nsplitaddress\nuse Email::Address::XS qw(splitaddress);\nmy ($user, $host) = splitaddress($stringaddress);\n\nTakes an escaped address and split it into pair of unescaped user part and unescaped host\npart of address. If splitting input address into these two parts is not possible then this\nfunction returns pair of undefs.\n\nAvailable since version 1.01.\n"
                },
                {
                    "name": "Class Methods",
                    "content": "new\nmy $emptyaddress = Email::Address::XS->new();\nmy $winstonsaddress = Email::Address::XS->new(phrase => 'Winston Smith', user => 'winston.smith', host => 'recdep.minitrue', comment => 'Records Department');\nmy $juliasaddress = Email::Address::XS->new('Julia', 'julia@ficdep.minitrue');\nmy $usersaddress = Email::Address::XS->new(address => 'user@oceania');\nmy $onlyname = Email::Address::XS->new(phrase => 'Name');\nmy $copyofwinstonsaddress = Email::Address::XS->new(copy => $winstonsaddress);\n\nConstructs and returns a new \"Email::Address::XS\" object. Takes named list of arguments:\nphrase, address, user, host, comment and copy. An argument address takes precedence over\nuser and host.\n\nWhen an argument copy is specified then it is expected an Email::Address::XS object and a\ncloned copy of that object is returned. All other parameters are ignored.\n\nOld syntax from the Email::Address module is supported too. Takes one to four positional\narguments: phrase, address comment, and original string. Passing an argument original is\ndeprecated, ignored and throws a warning.\n\nparse\nmy $winstonsaddress = Email::Address::XS->parse('\"Winston Smith\" <winston.smith@recdep.minitrue> (Records Department)');\nmy @usersaddresses = Email::Address::XS->parse('user1@oceania, user2@oceania');\n\nParses an input string and returns a list of an Email::Address::XS objects. Same as the\nfunction \"parseemailaddresses\" but this one is class method.\n\nIn scalar context this function returns just first parsed object. If more then one object\nwas parsed then \"isvalid\" method on returned object returns false. If no object was parsed\nthen empty Email::Address::XS object is returned.\n\nPrior to version 1.01 return value in scalar context is undef when no object was parsed.\n\nparsebareaddress\nmy $winstonsaddress = Email::Address::XS->parsebareaddress('winston.smith@recdep.minitrue');\n\nParses an input string as one bare email address (addr spec) which does not allow phrase\npart or angle brackets around email address and returns an Email::Address::XS object. It is\njust a wrapper around \"address\" method. Method \"isvalid\" can be used to check if parsing\nwas successful.\n\nAvailable since version 1.01.\n"
                },
                {
                    "name": "Object Methods",
                    "content": "format\nmy $string = $address->format();\n\nReturns formatted Email::Address::XS object as a string. This method throws a warning when\n\"user\" or \"host\" part of the email address is invalid or empty string.\n\nisvalid\nmy $isvalid = $address->isvalid();\n\nReturns true if the parse function or method which created this Email::Address::XS object\nhad not received any syntax error on input string and also that \"user\" and \"host\" part of\nthe email address are not empty strings.\n\nThus this function can be used for checking if Email::Address::XS object is valid before\ncalling \"format\" method on it.\n\nAvailable since version 1.01.\n\nphrase\nmy $phrase = $address->phrase();\n$address->phrase('Winston Smith');\n\nAccessor and mutator for the phrase (display name).\n\nuser\nmy $user = $address->user();\n$address->user('winston.smith');\n\nAccessor and mutator for the unescaped user (local/mailbox) part of an address.\n\nhost\nmy $host = $address->host();\n$address->host('recdep.minitrue');\n\nAccessor and mutator for the unescaped host (domain) part of an address.\n\nSince version 1.03 this method checks if setting a new value is syntactically valid. If not\nundef is set and returned.\n\naddress\nmy $stringaddress = $address->address();\n$address->address('winston.smith@recdep.minitrue');\n\nAccessor and mutator for the escaped address (addr spec).\n\nInternally this module stores a user and a host part of an address separately. Function\n\"composeaddress\" is used for composing full address and function \"splitaddress\" for\nsplitting into a user and a host parts. If splitting new address into these two parts is not\npossible then this method returns undef and sets both parts to undef.\n\ncomment\nmy $comment = $address->comment();\n$address->comment('Records Department');\n\nAccessor and mutator for the comment which is formatted after an address. A comment can\ncontain another nested comments in round brackets. When setting new comment this method\ncheck if brackets are balanced. If not undef is set and returned.\n\nname\nmy $name = $address->name();\n\nThis method tries to return a name which belongs to the address. It returns either \"phrase\"\nor \"comment\" or \"user\" part of the address or empty string (first defined value in this\norder). But it never returns undef.\n\nasstring\nmy $address = Email::Address::XS->new(phrase => 'Winston Smith', address => 'winston.smith@recdep.minitrue');\nmy $stringified = $address->asstring();\n\nThis method is used for object stringification. It returns string representation of object.\nBy default object is stringified to \"format\".\n\nAvailable since version 1.01.\n\noriginal\nmy $address = Email::Address::XS->parse('(Winston) \"Smith\"   <winston.smith@recdep.minitrue> (Minitrue)');\nmy $original = $address->original();\n# (Winston) \"Smith\"   <winston.smith@recdep.minitrue> (Minitrue)\nmy $format = $address->format();\n# Smith <winston.smith@recdep.minitrue> (Minitrue)\n\nThis method returns original part of the string which was used for parsing current\nEmail::Address::XS object. If object was not created by parsing input string, then this\nmethod returns undef.\n\nNote that \"format\" method does not have to return same original string.\n\nAvailable since version 1.01.\n"
                },
                {
                    "name": "Overloaded Operators",
                    "content": "stringify\nmy $address = Email::Address::XS->new(phrase => 'Winston Smith', address => 'winston.smith@recdep.minitrue');\nprint \"Winston's address is $address.\";\n# Winston's address is \"Winston Smith\" <winston.smith@recdep.minitrue>.\n\nStringification is done by method \"asstring\".\n"
                },
                {
                    "name": "Deprecated Functions and Variables",
                    "content": "For compatibility with the Email::Address module there are defined some deprecated functions and\nvariables. Do not use them in new code. Their usage throws warnings.\n\nAltering deprecated variable $Email::Address::XS::STRINGIFY changes method which is called for\nobjects stringification.\n\nDeprecated cache functions \"purgecache\", \"disablecache\" and \"enablecache\" are noop and do\nnothing.\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "RFC 822 <https://tools.ietf.org/html/rfc822>, RFC 2822 <https://tools.ietf.org/html/rfc2822>,\nRFC 5322 <https://tools.ietf.org/html/rfc5322>, Email::MIME::Header::AddressList,\nEmail::Address, Email::Address::List, Email::AddressParser\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Pali <pali@cpan.org>\n",
            "subsections": []
        },
        "COPYRIGHT AND LICENSE": {
            "content": "Copyright (C) 2015-2018 by Pali <pali@cpan.org>\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself, either Perl version 5.6.0 or, at your option, any later version of Perl 5 you may\nhave available.\n\nDovecot parser is licensed under The MIT License and copyrighted by Dovecot authors.\n",
            "subsections": []
        }
    },
    "summary": "Email::Address::XS - Parse and format RFC 5322 email addresses and groups",
    "flags": [],
    "examples": [],
    "see_also": []
}