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 $f = Mail::Message::Field->new(Cc =>
17                       'Mail::Box <mailbox@overmeer.net>');
18
19        my $cc = Mail::Message::Field->new('Cc');
20        $cc->addAddress('Mail::Box <mailbox@overmeer.net>');
21        $cc->addAddress
22          ( phrase  => 'Mail::Box'
23          , email   => 'mailbox@overmeer.net'
24          , comment => 'Our mailing list'     # deprecated by RFC
25          );
26
27        mu $ma = Mail::Message::Field::Address->new(...);
28        $cc->addAddress($ma);
29
30        my $mi = Mail::Identity->new(...);
31        $cc->addAddress($mi);
32
33        my $g  = Mail::Message::Field::AddrGroup->new(...);
34        $cc->addGroup($g);
35

DESCRIPTION

37       All header fields which contain e-mail addresses only.  Not all address
38       fields have the same possibilities, but they are all parsed the same:
39       you never know how broken the applications are which produce those mes‐
40       sages.
41
42       When you try to create constructs which are not allowed for a certain
43       kind of field, you will be warned.
44

OVERLOADED

46       overload: ""
47
48           See "OVERLOADED" in Mail::Message::Field
49
50       overload: +0
51
52           See "OVERLOADED" in Mail::Message::Field
53
54       overload: <=>
55
56           See "OVERLOADED" in Mail::Message::Field
57
58       overload: bool
59
60           See "OVERLOADED" in Mail::Message::Field
61
62       overload: cmp
63
64           See "OVERLOADED" in Mail::Message::Field
65
66       overload: stringification
67
68           See "OVERLOADED" in Mail::Message::Field::Full
69

METHODS

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

DETAILS

DIAGNOSTICS

436       Warning: Field content is not numerical: $content
437
438       The numeric value of a field is requested (for instance the "Lines" or
439       "Content-Length" fields should be numerical), however the data contains
440       weird characters.
441
442       Warning: Illegal character in charset '$charset'
443
444       The field is created with an utf8 string which only contains data from
445       the specified character set.  However, that character set can never be
446       a valid name because it contains characters which are not permitted.
447
448       Warning: Illegal character in field name $name
449
450       A new field is being created which does contain characters not permit‐
451       ted by the RFCs.  Using this field in messages may break other e-mail
452       clients or transfer agents, and therefore mutulate or extinguish your
453       message.
454
455       Warning: Illegal character in language '$lang'
456
457       The field is created with data which is specified to be in a certain
458       language, however, the name of the language cannot be valid: it con‐
459       tains characters which are not permitted by the RFCs.
460
461       Warning: Illegal encoding '$encoding', used 'q'
462
463       The RFCs only permit base64 ("b " or "B ") or quoted-printable ("q" or
464       "Q") encoding.  Other than these four options are illegal.
465
466       Error: No attributes for address fields.
467
468       Is is not possible to add attributes to address fields: it is not per‐
469       mitted by the RFCs.
470
471       Error: Package $package does not implement $method.
472
473       Fatal error: the specific package (or one of its superclasses) does not
474       implement this method where it should. This message means that some
475       other related classes do implement this method however the class at
476       hand does not.  Probably you should investigate this and probably
477       inform the author of the package.
478

LICENSE

484       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
485       ChangeLog.
486
487       This program is free software; you can redistribute it and/or modify it
488       under the same terms as Perl itself.  See
489       http://www.perl.com/perl/misc/Artistic.html
490
491
492
493perl v5.8.8                       2007-03-25Mail::Message::Field::Addresses(3)