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

OVERLOADED

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

METHODS

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

DIAGNOSTICS

347       Warning: Field content is not numerical: $content
348           The numeric value of a field is requested (for instance the "Lines"
349           or "Content-Length" fields should be numerical), however the data
350           contains weird characters.
351
352       Warning: Illegal character in charset '$charset'
353           The field is created with an utf8 string which only contains data
354           from the specified character set.  However, that character set can
355           never be a valid name because it contains characters which are not
356           permitted.
357
358       Warning: Illegal character in field name $name
359           A new field is being created which does contain characters not
360           permitted by the RFCs.  Using this field in messages may break
361           other e-mail clients or transfer agents, and therefore mutulate or
362           extinguish your message.
363
364       Warning: Illegal character in language '$lang'
365           The field is created with data which is specified to be in a
366           certain language, however, the name of the language cannot be
367           valid: it contains characters which are not permitted by the RFCs.
368
369       Warning: Illegal encoding '$encoding', used 'q'
370           The RFCs only permit base64 ("b " or "B ") or quoted-printable ("q"
371           or "Q") encoding.  Other than these four options are illegal.
372
373       Error: No attributes for address fields.
374           Is is not possible to add attributes to address fields: it is not
375           permitted by the RFCs.
376
377       Error: Package $package does not implement $method.
378           Fatal error: the specific package (or one of its superclasses) does
379           not implement this method where it should. This message means that
380           some other related classes do implement this method however the
381           class at hand does not.  Probably you should investigate this and
382           probably inform the author of the package.
383

LICENSE

389       Copyrights 2001-2011 by Mark Overmeer. For other contributors see
390       ChangeLog.
391
392       This program is free software; you can redistribute it and/or modify it
393       under the same terms as Perl itself.  See
394       http://www.perl.com/perl/misc/Artistic.html
395
396
397
398perl v5.12.3                      2011-01-26Mail::Message::Field::Addresses(3)