Email::Address::XS(3pm)

1Email::Address::XS(3) User Contributed Perl DocumentationEmail::Address::XS(3)
2
3
4

NAME

6       Email::Address::XS - Parse and format RFC 5322 email addresses and
7       groups
8

SYNOPSIS

10         use Email::Address::XS;
11
12         my $winstons_address = Email::Address::XS->new(phrase => 'Winston Smith', user => 'winston.smith', host => 'recdep.minitrue', comment => 'Records Department');
13         print $winstons_address->address();
14         # winston.smith@recdep.minitrue
15
16         my $julias_address = Email::Address::XS->new('Julia', 'julia@ficdep.minitrue');
17         print $julias_address->format();
18         # Julia <julia@ficdep.minitrue>
19
20         my $users_address = Email::Address::XS->parse('user <user@oceania>');
21         print $users_address->host();
22         # oceania
23
24         my $goldsteins_address = Email::Address::XS->parse_bare_address('goldstein@brotherhood.oceania');
25         print $goldsteins_address->user();
26         # goldstein
27
28         my @addresses = Email::Address::XS->parse('"Winston Smith" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>');
29         # ($winstons_address, $julias_address)
30
31
32         use Email::Address::XS qw(format_email_addresses format_email_groups parse_email_addresses parse_email_groups);
33
34         my $addresses_string = format_email_addresses($winstons_address, $julias_address, $users_address);
35         # "Winston Smith" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>, user <user@oceania>
36
37         my @addresses = map { $_->address() } parse_email_addresses($addresses_string);
38         # ('winston.smith@recdep.minitrue', 'julia@ficdep.minitrue', 'user@oceania')
39
40         my $groups_string = format_email_groups('Brotherhood' => [ $winstons_address, $julias_address ], undef() => [ $users_address ]);
41         # Brotherhood: "Winston Smith" <winston.smith@recdep.minitrue> (Records Department), Julia <julia@ficdep.minitrue>;, user <user@oceania>
42
43         my @groups = parse_email_groups($groups_string);
44         # ('Brotherhood' => [ $winstons_address, $julias_address ], undef() => [ $users_address ])
45
46
47         use Email::Address::XS qw(compose_address split_address);
48
49         my ($user, $host) = split_address('julia(outer party)@ficdep.minitrue');
50         # ('julia', 'ficdep.minitrue')
51
52         my $string = compose_address('charrington"@"shop', 'thought.police.oceania');
53         # "charrington\"@\"shop"@thought.police.oceania
54

DESCRIPTION

56       This module implements RFC 5322 <https://tools.ietf.org/html/rfc5322>
57       parser and formatter of email addresses and groups. It parses an input
58       string from email headers which contain a list of email addresses or a
59       groups of email addresses (like From, To, Cc, Bcc, Reply-To, Sender,
60       ...). Also it can generate a string value for those headers from a list
61       of email addresses objects. Module is backward compatible with RFC 2822
62       <https://tools.ietf.org/html/rfc2822> and RFC 822
63       <https://tools.ietf.org/html/rfc822>.
64
65       Parser and formatter functionality is implemented in XS and uses shared
66       code from Dovecot IMAP server.
67
68       It is a drop-in replacement for the Email::Address module which has
69       several security issues. E.g. issue CVE-2015-7686 (Algorithmic
70       complexity vulnerability) <https://cve.mitre.org/cgi-
71       bin/cvename.cgi?name=CVE-2015-7686>, which allows remote attackers to
72       cause denial of service, is still present in Email::Address version
73       1.908.
74
75       Email::Address::XS module was created to finally fix CVE-2015-7686.
76
77       Existing applications that use Email::Address module could be easily
78       switched to Email::Address::XS module. In most cases only changing "use
79       Email::Address" to "use Email::Address::XS" and replacing every
80       "Email::Address" occurrence with "Email::Address::XS" is sufficient.
81
82       So unlike Email::Address, this module does not use regular expressions
83       for parsing but instead native XS implementation parses input string
84       sequentially according to RFC 5322 grammar.
85
86       Additionally it has support also for named groups and so can be use
87       instead of the Email::Address::List module.
88
89       If you are looking for the module which provides object representation
90       for the list of email addresses suitable for the MIME email headers,
91       see Email::MIME::Header::AddressList.
92
93   EXPORT
94       None by default. Exportable functions are: "parse_email_addresses",
95       "parse_email_groups", "format_email_addresses", "format_email_groups",
96       "compose_address", "split_address".
97
98   Exportable Functions
99       format_email_addresses
100             use Email::Address::XS qw(format_email_addresses);
101
102             my $winstons_address = Email::Address::XS->new(phrase => 'Winston Smith', address => 'winston@recdep.minitrue');
103             my $julias_address = Email::Address::XS->new(phrase => 'Julia', address => 'julia@ficdep.minitrue');
104             my @addresses = ($winstons_address, $julias_address);
105             my $string = format_email_addresses(@addresses);
106             print $string;
107             # "Winston Smith" <winston@recdep.minitrue>, Julia <julia@ficdep.minitrue>
108
109           Takes a list of email address objects and returns one formatted
110           string of those email addresses.
111
112       format_email_groups
113             use Email::Address::XS qw(format_email_groups);
114
115             my $winstons_address = Email::Address::XS->new(phrase => 'Winston Smith', user => 'winston.smith', host => 'recdep.minitrue');
116             my $julias_address = Email::Address::XS->new('Julia', 'julia@ficdep.minitrue');
117             my $users_address = Email::Address::XS->new(address => 'user@oceania');
118
119             my $groups_string = format_email_groups('Brotherhood' => [ $winstons_address, $julias_address ], undef() => [ $users_address ]);
120             print $groups_string;
121             # Brotherhood: "Winston Smith" <winston.smith@recdep.minitrue>, Julia <julia@ficdep.minitrue>;, user@oceania
122
123             my $undisclosed_string = format_email_groups('undisclosed-recipients' => []);
124             print $undisclosed_string;
125             # undisclosed-recipients:;
126
127           Like "format_email_addresses" but this method takes pairs which
128           consist of a group display name and a reference to address list. If
129           a group is not undef then address list is formatted inside named
130           group.
131
132       parse_email_addresses
133             use Email::Address::XS qw(parse_email_addresses);
134
135             my $string = '"Winston Smith" <winston.smith@recdep.minitrue>, Julia <julia@ficdep.minitrue>, user@oceania';
136             my @addresses = parse_email_addresses($string);
137             # @addresses now contains three Email::Address::XS objects, one for each address
138
139           Parses an input string and returns a list of Email::Address::XS
140           objects. Optional second string argument specifies class name for
141           blessing new objects.
142
143       parse_email_groups
144             use Email::Address::XS qw(parse_email_groups);
145
146             my $string = 'Brotherhood: "Winston Smith" <winston.smith@recdep.minitrue>, Julia <julia@ficdep.minitrue>;, user@oceania, undisclosed-recipients:;';
147             my @groups = parse_email_groups($string);
148             # @groups now contains list ('Brotherhood' => [ $winstons_object, $julias_object ], undef() => [ $users_object ], 'undisclosed-recipients' => [])
149
150           Like "parse_email_addresses" but this function returns a list of
151           pairs: a group display name and a reference to a list of addresses
152           which belongs to that named group.  An undef value for a group
153           means that a following list of addresses is not inside any named
154           group. An output is in a same format as a input for the function
155           "format_email_groups".  This function preserves order of groups and
156           does not do any de-duplication or merging.
157
158       compose_address
159             use Email::Address::XS qw(compose_address);
160             my $string_address = compose_address($user, $host);
161
162           Takes an unescaped user part and unescaped host part of an address
163           and returns escaped address.
164
165           Available since version 1.01.
166
167       split_address
168             use Email::Address::XS qw(split_address);
169             my ($user, $host) = split_address($string_address);
170
171           Takes an escaped address and split it into pair of unescaped user
172           part and unescaped host part of address. If splitting input address
173           into these two parts is not possible then this function returns
174           pair of undefs.
175
176           Available since version 1.01.
177
178   Class Methods
179       new
180             my $empty_address = Email::Address::XS->new();
181             my $winstons_address = Email::Address::XS->new(phrase => 'Winston Smith', user => 'winston.smith', host => 'recdep.minitrue', comment => 'Records Department');
182             my $julias_address = Email::Address::XS->new('Julia', 'julia@ficdep.minitrue');
183             my $users_address = Email::Address::XS->new(address => 'user@oceania');
184             my $only_name = Email::Address::XS->new(phrase => 'Name');
185             my $copy_of_winstons_address = Email::Address::XS->new(copy => $winstons_address);
186
187           Constructs and returns a new "Email::Address::XS" object. Takes
188           named list of arguments: phrase, address, user, host, comment and
189           copy.  An argument address takes precedence over user and host.
190
191           When an argument copy is specified then it is expected an
192           Email::Address::XS object and a cloned copy of that object is
193           returned. All other parameters are ignored.
194
195           Old syntax from the Email::Address module is supported too. Takes
196           one to four positional arguments: phrase, address comment, and
197           original string. Passing an argument original is deprecated,
198           ignored and throws a warning.
199
200       parse
201             my $winstons_address = Email::Address::XS->parse('"Winston Smith" <winston.smith@recdep.minitrue> (Records Department)');
202             my @users_addresses = Email::Address::XS->parse('user1@oceania, user2@oceania');
203
204           Parses an input string and returns a list of an Email::Address::XS
205           objects. Same as the function "parse_email_addresses" but this one
206           is class method.
207
208           In scalar context this function returns just first parsed object.
209           If more then one object was parsed then "is_valid" method on
210           returned object returns false. If no object was parsed then empty
211           Email::Address::XS object is returned.
212
213           Prior to version 1.01 return value in scalar context is undef when
214           no object was parsed.
215
216       parse_bare_address
217             my $winstons_address = Email::Address::XS->parse_bare_address('winston.smith@recdep.minitrue');
218
219           Parses an input string as one bare email address (addr spec) which
220           does not allow phrase part or angle brackets around email address
221           and returns an Email::Address::XS object. It is just a wrapper
222           around "address" method. Method "is_valid" can be used to check if
223           parsing was successful.
224
225           Available since version 1.01.
226
227   Object Methods
228       format
229             my $string = $address->format();
230
231           Returns formatted Email::Address::XS object as a string. This
232           method throws a warning when "user" or "host" part of the email
233           address is invalid or empty string.
234
235       is_valid
236             my $is_valid = $address->is_valid();
237
238           Returns true if the parse function or method which created this
239           Email::Address::XS object had not received any syntax error on
240           input string and also that "user" and "host" part of the email
241           address are not empty strings.
242
243           Thus this function can be used for checking if Email::Address::XS
244           object is valid before calling "format" method on it.
245
246           Available since version 1.01.
247
248       phrase
249             my $phrase = $address->phrase();
250             $address->phrase('Winston Smith');
251
252           Accessor and mutator for the phrase (display name).
253
254       user
255             my $user = $address->user();
256             $address->user('winston.smith');
257
258           Accessor and mutator for the unescaped user (local/mailbox) part of
259           an address.
260
261       host
262             my $host = $address->host();
263             $address->host('recdep.minitrue');
264
265           Accessor and mutator for the unescaped host (domain) part of an
266           address.
267
268           Since version 1.03 this method checks if setting a new value is
269           syntactically valid. If not undef is set and returned.
270
271       address
272             my $string_address = $address->address();
273             $address->address('winston.smith@recdep.minitrue');
274
275           Accessor and mutator for the escaped address (addr spec).
276
277           Internally this module stores a user and a host part of an address
278           separately. Function "compose_address" is used for composing full
279           address and function "split_address" for splitting into a user and
280           a host parts. If splitting new address into these two parts is not
281           possible then this method returns undef and sets both parts to
282           undef.
283
284       comment
285             my $comment = $address->comment();
286             $address->comment('Records Department');
287
288           Accessor and mutator for the comment which is formatted after an
289           address. A comment can contain another nested comments in round
290           brackets. When setting new comment this method check if brackets
291           are balanced. If not undef is set and returned.
292
293       name
294             my $name = $address->name();
295
296           This method tries to return a name which belongs to the address. It
297           returns either "phrase" or "comment" or "user" part of the address
298           or empty string (first defined value in this order). But it never
299           returns undef.
300
301       as_string
302             my $address = Email::Address::XS->new(phrase => 'Winston Smith', address => 'winston.smith@recdep.minitrue');
303             my $stringified = $address->as_string();
304
305           This method is used for object stringification. It returns string
306           representation of object. By default object is stringified to
307           "format".
308
309           Available since version 1.01.
310
311       original
312             my $address = Email::Address::XS->parse('(Winston) "Smith"   <winston.smith@recdep.minitrue> (Minitrue)');
313             my $original = $address->original();
314             # (Winston) "Smith"   <winston.smith@recdep.minitrue> (Minitrue)
315             my $format = $address->format();
316             # Smith <winston.smith@recdep.minitrue> (Minitrue)
317
318           This method returns original part of the string which was used for
319           parsing current Email::Address::XS object. If object was not
320           created by parsing input string, then this method returns undef.
321
322           Note that "format" method does not have to return same original
323           string.
324
325           Available since version 1.01.
326
327   Overloaded Operators
328       stringify
329             my $address = Email::Address::XS->new(phrase => 'Winston Smith', address => 'winston.smith@recdep.minitrue');
330             print "Winston's address is $address.";
331             # Winston's address is "Winston Smith" <winston.smith@recdep.minitrue>.
332
333           Stringification is done by method "as_string".
334
335   Deprecated Functions and Variables
336       For compatibility with the Email::Address module there are defined some
337       deprecated functions and variables.  Do not use them in new code. Their
338       usage throws warnings.
339
340       Altering deprecated variable $Email::Address::XS::STRINGIFY changes
341       method which is called for objects stringification.
342
343       Deprecated cache functions "purge_cache", "disable_cache" and
344       "enable_cache" are noop and do nothing.
345

AUTHOR

354       Pali <pali@cpan.org>
355

COPYRIGHT AND LICENSE

357       Copyright (C) 2015-2018 by Pali <pali@cpan.org>
358
359       This library is free software; you can redistribute it and/or modify it
360       under the same terms as Perl itself, either Perl version 5.6.0 or, at
361       your option, any later version of Perl 5 you may have available.
362
363       Dovecot parser is licensed under The MIT License and copyrighted by
364       Dovecot authors.
365
366
367
368perl v5.36.0                      2022-08-08             Email::Address::XS(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE