Mail::Message::Field::Addresses(3pm)

1Mail::Message::Field::AUdsderresCsoenst(r3i)buted Perl DMoaciulm:e:nMteastsiaogne::Field::Addresses(3)
2
3
4

NAME

6       Mail::Message::Field::Addresses - Fields with e-mail addresses
7

INHERITANCE

9        Mail::Message::Field::Addresses
10          is a Mail::Message::Field::Structured
11          is a Mail::Message::Field::Full
12          is a Mail::Message::Field
13          is a Mail::Reporter
14

SYNOPSIS

16         my $cc = Mail::Message::Field::Full->new('Cc');
17         my $me = Mail::Message::Field::Address->parse('"Test" <test@mail.box>')
18            or die;
19
20         my $other = Mail::Message::Field::Address->new(phrase => 'Other'
21            , address => 'other@example.com')
22            or die;
23
24         $cc->addAddress($me);
25         $cc->addAddress($other, group => 'them');
26         $cc->addAddress(phrase => 'third', address => 'more@any.museum'
27           , group => 'them');
28
29         my $group = $cc->addGroup(name => 'collegues');
30         $group->addAddress($me);
31         $group->addAddress(phrase => "You", address => 'you@example.com');
32
33         my $msg = Mail::Message->build(Cc => $cc);
34         print $msg->string;
35
36         my $g  = Mail::Message::Field::AddrGroup->new(...);
37         $cc->addGroup($g);
38

DESCRIPTION

40       All header fields which contain e-mail addresses only.  Not all address
41       fields have the same possibilities, but they are all parsed the same:
42       you never know how broken the applications are which produce those
43       messages.
44
45       When you try to create constructs which are not allowed for a certain
46       kind of field, you will be warned.
47
48       Extends "DESCRIPTION" in Mail::Message::Field::Structured.
49

OVERLOADED

51       Extends "OVERLOADED" in Mail::Message::Field::Structured.
52
53       overload: ""
54           Inherited, see "OVERLOADED" in Mail::Message::Field
55
56       overload: 0+
57           Inherited, see "OVERLOADED" in Mail::Message::Field
58
59       overload: <=>
60           Inherited, see "OVERLOADED" in Mail::Message::Field
61
62       overload: bool
63           Inherited, see "OVERLOADED" in Mail::Message::Field
64
65       overload: cmp
66           Inherited, see "OVERLOADED" in Mail::Message::Field
67
68       overload: stringification
69           Inherited, see "OVERLOADED" in Mail::Message::Field::Full
70

METHODS

72       Extends "METHODS" in Mail::Message::Field::Structured.
73
74   Constructors
75       Extends "Constructors" in Mail::Message::Field::Structured.
76
77       $obj->clone()
78           Inherited, see "Constructors" in Mail::Message::Field
79
80       Mail::Message::Field::Addresses->from($field, %options)
81           Inherited, see "Constructors" in Mail::Message::Field::Full
82
83       Mail::Message::Field::Addresses->new()
84            -Option    --Defined in                      --Default
85             attributes  Mail::Message::Field::Structured  <ignored>
86             charset     Mail::Message::Field::Full        undef
87             datum       Mail::Message::Field::Structured  undef
88             encoding    Mail::Message::Field::Full        'q'
89             force       Mail::Message::Field::Full        false
90             language    Mail::Message::Field::Full        undef
91             log         Mail::Reporter                    'WARNINGS'
92             trace       Mail::Reporter                    'WARNINGS'
93
94           attributes => ATTRS
95           charset => STRING
96           datum => STRING
97           encoding => 'q'|'Q'|'b'|'B'
98           force => BOOLEAN
99           language => STRING
100           log => LEVEL
101           trace => LEVEL
102
103   The field
104       Extends "The field" in Mail::Message::Field::Structured.
105
106       $obj->isStructured()
107       Mail::Message::Field::Addresses->isStructured()
108           Inherited, see "The field" in Mail::Message::Field
109
110       $obj->length()
111           Inherited, see "The field" in Mail::Message::Field
112
113       $obj->nrLines()
114           Inherited, see "The field" in Mail::Message::Field
115
116       $obj->print( [$fh] )
117           Inherited, see "The field" in Mail::Message::Field
118
119       $obj->size()
120           Inherited, see "The field" in Mail::Message::Field
121
122       $obj->string( [$wrap] )
123           Inherited, see "The field" in Mail::Message::Field
124
125       $obj->toDisclose()
126           Inherited, see "The field" in Mail::Message::Field
127
128   Access to the name
129       Extends "Access to the name" in Mail::Message::Field::Structured.
130
131       $obj->Name()
132           Inherited, see "Access to the name" in Mail::Message::Field
133
134       $obj->name()
135           Inherited, see "Access to the name" in Mail::Message::Field
136
137       $obj->wellformedName( [STRING] )
138           Inherited, see "Access to the name" in Mail::Message::Field
139
140   Access to the body
141       Extends "Access to the body" in Mail::Message::Field::Structured.
142
143       $obj->body()
144           Inherited, see "Access to the body" in Mail::Message::Field
145
146       $obj->decodedBody(%options)
147           Inherited, see "Access to the body" in Mail::Message::Field::Full
148
149       $obj->folded()
150           Inherited, see "Access to the body" in Mail::Message::Field
151
152       $obj->foldedBody( [$body] )
153           Inherited, see "Access to the body" in Mail::Message::Field
154
155       $obj->stripCFWS( [STRING] )
156       Mail::Message::Field::Addresses->stripCFWS( [STRING] )
157           Inherited, see "Access to the body" in Mail::Message::Field
158
159       $obj->unfoldedBody( [$body, [$wrap]] )
160           Inherited, see "Access to the body" in Mail::Message::Field
161
162   Access to the content
163       Extends "Access to the content" in Mail::Message::Field::Structured.
164
165       $obj->addAddress( [$address], %options )
166           Add an $address to the field.  The addresses are organized in
167           groups.  If no group is specified, the default group is taken to
168           store the address in.  If no $address is specified, the option must
169           be sufficient to create a Mail::Message::Field::Address from.  See
170           the %options of Mail::Message::Field::Address::new().
171
172            -Option--Default
173             group   ''
174
175           group => STRING
176       $obj->addAttribute(...)
177           Attributes are not supported for address fields.
178
179       $obj->addGroup($group|%options)
180           Add a group of addresses to this field.  A $group can be specified,
181           which is a Mail::Message::Field::AddrGroup object, or one is
182           created for you using the %options.  The group is returned.
183
184            -Option--Default
185             name    ''
186
187           name => STRING
188       $obj->addresses()
189           Returns a list with all addresses defined in any group of
190           addresses: all addresses which are specified on the line.  The
191           addresses are Mail::Message::Field::Address objects.
192
193           example:
194
195            my @addr = $field->addresses;
196
197       $obj->attrPairs()
198           Inherited, see "Access to the content" in
199           Mail::Message::Field::Structured
200
201       $obj->attribute( $object|<STRING, %options>|<$name,$value,%options> )
202           Inherited, see "Access to the content" in
203           Mail::Message::Field::Structured
204
205       $obj->attributes()
206           Inherited, see "Access to the content" in
207           Mail::Message::Field::Structured
208
209       $obj->beautify()
210           Inherited, see "Access to the content" in
211           Mail::Message::Field::Full
212
213       $obj->comment( [STRING] )
214           Inherited, see "Access to the content" in Mail::Message::Field
215
216       $obj->createComment(STRING, %options)
217       Mail::Message::Field::Addresses->createComment(STRING, %options)
218           Inherited, see "Access to the content" in
219           Mail::Message::Field::Full
220
221       $obj->createPhrase(STRING, %options)
222       Mail::Message::Field::Addresses->createPhrase(STRING, %options)
223           Inherited, see "Access to the content" in
224           Mail::Message::Field::Full
225
226       $obj->group($name)
227           Returns the group of addresses with the specified $name, or "undef"
228           if it does not exist.  If $name is "undef", then the default groep
229           is returned.
230
231       $obj->groupNames()
232           Returns a list with all group names which are defined.
233
234       $obj->groups()
235           Returns all address groups which are defined in this field.  Each
236           element is a Mail::Message::Field::AddrGroup object.
237
238       $obj->study()
239           Inherited, see "Access to the content" in Mail::Message::Field
240
241       $obj->toDate( [$time] )
242       Mail::Message::Field::Addresses->toDate( [$time] )
243           Inherited, see "Access to the content" in Mail::Message::Field
244
245       $obj->toInt()
246           Inherited, see "Access to the content" in Mail::Message::Field
247
248   Other methods
249       Extends "Other methods" in Mail::Message::Field::Structured.
250
251       $obj->dateToTimestamp(STRING)
252       Mail::Message::Field::Addresses->dateToTimestamp(STRING)
253           Inherited, see "Other methods" in Mail::Message::Field
254
255   Internals
256       Extends "Internals" in Mail::Message::Field::Structured.
257
258       $obj->consume( $line | <$name,<$body|$objects>> )
259           Inherited, see "Internals" in Mail::Message::Field
260
261       $obj->decode(STRING, %options)
262       Mail::Message::Field::Addresses->decode(STRING, %options)
263           Inherited, see "Internals" in Mail::Message::Field::Full
264
265       $obj->defaultWrapLength( [$length] )
266           Inherited, see "Internals" in Mail::Message::Field
267
268       $obj->encode(STRING, %options)
269           Inherited, see "Internals" in Mail::Message::Field::Full
270
271       $obj->fold( $name, $body, [$maxchars] )
272       Mail::Message::Field::Addresses->fold( $name, $body, [$maxchars] )
273           Inherited, see "Internals" in Mail::Message::Field
274
275       $obj->setWrapLength( [$length] )
276           Inherited, see "Internals" in Mail::Message::Field
277
278       $obj->stringifyData(STRING|ARRAY|$objects)
279           Inherited, see "Internals" in Mail::Message::Field
280
281       $obj->unfold(STRING)
282           Inherited, see "Internals" in Mail::Message::Field
283
284   Parsing
285       Extends "Parsing" in Mail::Message::Field::Structured.
286
287       $obj->consumeAddress(STRING, %options)
288           Try to destilate address information from the STRING.   Returned
289           are an address object and the left-over string.  If no address was
290           found, the first returned value is "undef".
291
292       $obj->consumeComment(STRING)
293       Mail::Message::Field::Addresses->consumeComment(STRING)
294           Inherited, see "Parsing" in Mail::Message::Field::Full
295
296       $obj->consumeDomain(STRING)
297           Try to get a valid domain representation from STRING.  Returned are
298           the domain string as found (or "undef") and the rest of the string.
299
300       $obj->consumeDotAtom(STRING)
301           Inherited, see "Parsing" in Mail::Message::Field::Full
302
303       $obj->consumePhrase(STRING)
304       Mail::Message::Field::Addresses->consumePhrase(STRING)
305           Inherited, see "Parsing" in Mail::Message::Field::Full
306
307       $obj->datum( [$value] )
308           Inherited, see "Parsing" in Mail::Message::Field::Structured
309
310       $obj->parse(STRING)
311           Inherited, see "Parsing" in Mail::Message::Field::Full
312
313       $obj->produceBody()
314           Inherited, see "Parsing" in Mail::Message::Field::Full
315
316   Error handling
317       Extends "Error handling" in Mail::Message::Field::Structured.
318
319       $obj->AUTOLOAD()
320           Inherited, see "Error handling" in Mail::Reporter
321
322       $obj->addReport($object)
323           Inherited, see "Error handling" in Mail::Reporter
324
325       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
326       $callback] )
327       Mail::Message::Field::Addresses->defaultTrace( [$level]|[$loglevel,
328       $tracelevel]|[$level, $callback] )
329           Inherited, see "Error handling" in Mail::Reporter
330
331       $obj->errors()
332           Inherited, see "Error handling" in Mail::Reporter
333
334       $obj->log( [$level, [$strings]] )
335       Mail::Message::Field::Addresses->log( [$level, [$strings]] )
336           Inherited, see "Error handling" in Mail::Reporter
337
338       $obj->logPriority($level)
339       Mail::Message::Field::Addresses->logPriority($level)
340           Inherited, see "Error handling" in Mail::Reporter
341
342       $obj->logSettings()
343           Inherited, see "Error handling" in Mail::Reporter
344
345       $obj->notImplemented()
346           Inherited, see "Error handling" in Mail::Reporter
347
348       $obj->report( [$level] )
349           Inherited, see "Error handling" in Mail::Reporter
350
351       $obj->reportAll( [$level] )
352           Inherited, see "Error handling" in Mail::Reporter
353
354       $obj->trace( [$level] )
355           Inherited, see "Error handling" in Mail::Reporter
356
357       $obj->warnings()
358           Inherited, see "Error handling" in Mail::Reporter
359
360   Cleanup
361       Extends "Cleanup" in Mail::Message::Field::Structured.
362
363       $obj->DESTROY()
364           Inherited, see "Cleanup" in Mail::Reporter
365

DETAILS

367       Extends "DETAILS" in Mail::Message::Field::Structured.
368

DIAGNOSTICS

370       Warning: Field content is not numerical: $content
371           The numeric value of a field is requested (for instance the "Lines"
372           or "Content-Length" fields should be numerical), however the data
373           contains weird characters.
374
375       Warning: Illegal character in charset '$charset'
376           The field is created with an utf8 string which only contains data
377           from the specified character set.  However, that character set can
378           never be a valid name because it contains characters which are not
379           permitted.
380
381       Warning: Illegal character in field name $name
382           A new field is being created which does contain characters not
383           permitted by the RFCs.  Using this field in messages may break
384           other e-mail clients or transfer agents, and therefore mutulate or
385           extinguish your message.
386
387       Warning: Illegal character in language '$lang'
388           The field is created with data which is specified to be in a
389           certain language, however, the name of the language cannot be
390           valid: it contains characters which are not permitted by the RFCs.
391
392       Warning: Illegal encoding '$encoding', used 'q'
393           The RFCs only permit base64 ("b " or "B ") or quoted-printable ("q"
394           or "Q") encoding.  Other than these four options are illegal.
395
396       Error: No attributes for address fields.
397           Is is not possible to add attributes to address fields: it is not
398           permitted by the RFCs.
399
400       Error: Package $package does not implement $method.
401           Fatal error: the specific package (or one of its superclasses) does
402           not implement this method where it should. This message means that
403           some other related classes do implement this method however the
404           class at hand does not.  Probably you should investigate this and
405           probably inform the author of the package.
406

LICENSE

412       Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
413       contributors see ChangeLog.
414
415       This program is free software; you can redistribute it and/or modify it
416       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
417
418
419
420perl v5.34.0                      2022-03-01Mail::Message::Field::Addresses(3)