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

1Mail::Message::Field::SUtsreurctCuornetdr(i3b)uted PerlMDaoiclu:m:eMnetsastaigoen::Field::Structured(3)
2
3
4

NAME

6       Mail::Message::Field::Structured - one line of a structured message
7       header
8

INHERITANCE

10        Mail::Message::Field::Structured
11          is a Mail::Message::Field::Full
12          is a Mail::Message::Field
13          is a Mail::Reporter
14
15        Mail::Message::Field::Structured is extended by
16          Mail::Message::Field::Addresses
17          Mail::Message::Field::URIs
18

SYNOPSIS

20        my $f = Mail::Message::Field::Full
21                   ->new('Content-Type' => 'text/html');
22
23        my @encode = (charset => 'jp', use_continuations => 1);
24        $f->attribute('filename=passwd');
25        $f->attribute(filename => 'passwd', @encode);
26
27        my $attr = Mail::Message::Field::Attribute->new(...);
28        $f->attribute($attr);
29

DESCRIPTION

OVERLOADED

32       overload: ""
33
34           See "OVERLOADED" in Mail::Message::Field
35
36       overload: +0
37
38           See "OVERLOADED" in Mail::Message::Field
39
40       overload: <=>
41
42           See "OVERLOADED" in Mail::Message::Field
43
44       overload: bool
45
46           See "OVERLOADED" in Mail::Message::Field
47
48       overload: cmp
49
50           See "OVERLOADED" in Mail::Message::Field
51
52       overload: stringification
53
54           See "OVERLOADED" in Mail::Message::Field::Full
55

METHODS

57       Constructors
58
59       $obj->clone
60
61           See "Constructors" in Mail::Message::Field
62
63       Mail::Message::Field::Structured->from(FIELD, OPTIONS)
64
65           See "Constructors" in Mail::Message::Field::Full
66
67       Mail::Message::Field::Structured->new(DATA)
68
69           * new LINE
70               Pass a LINE as it could be found in a file: a (possibly folded)
71               line which is terminated by a new-line.
72
73           * new NAME, BODY, OPTIONS
74               A set of values which shape the line.
75
76           The NAME is a wellformed header name (you may use wellformedName())
77           to be sure about the casing.  The BODY is a string, one object, or
78           an ref-array of objects.  In case of objects, they must fit to the
79           constructor of the field: the types which are accepted may differ.
80           The optional ATTRIBUTE list contains Mail::Mes‐
81           sage::Field::Attribute objects.  Finally, there are some OPTIONS.
82
83            Option    --Defined in     --Default
84            attributes                   []
85            charset     Mail::Message::Field::Full  undef
86            datum                        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               There are various ways to specify these attributes: pass a ref‐
96               erence to an array which list of key-value pairs representing
97               attributes, or reference to a hash containing these pairs, or
98               an array with Mail::Message::Field::Attribute objects.
99
100           . charset STRING
101
102           . datum STRING
103
104               The method name body is very confusing, even in the RFC.  In
105               MailBox, for historical reasons, body() returns the past of the
106               field contents before the first semi-colon.  foldedBody() and
107               unfoldedBody() address the whole field.
108
109               There is no common name for the piece of data before the param‐
110               eters (attributes) in the field-content mentioned in the RFCs,
111               so let's call it datum.
112
113           . encoding 'q'⎪'Q'⎪'b'⎪'B'
114
115           . force BOOLEAN
116
117           . language STRING
118
119           . log LEVEL
120
121           . trace LEVEL
122
123           Example: of a structured field
124
125            my @attrs   = (Mail::Message::Field::Attribute->new(...), ...);
126            my @options = (extra => 'the color blue');
127            my $t = Mail::Message::Field::Full->new(To => \@addrs, @attrs, @options);
128
129       The field
130
131       $obj->isStructured
132
133       Mail::Message::Field::Structured->isStructured
134
135           See "The field" in Mail::Message::Field
136
137       $obj->length
138
139           See "The field" in Mail::Message::Field
140
141       $obj->nrLines
142
143           See "The field" in Mail::Message::Field
144
145       $obj->print([FILEHANDLE])
146
147           See "The field" in Mail::Message::Field
148
149       $obj->size
150
151           See "The field" in Mail::Message::Field
152
153       $obj->string([WRAP])
154
155           See "The field" in Mail::Message::Field
156
157       $obj->toDisclose
158
159           See "The field" in Mail::Message::Field
160
161       Access to the name
162
163       $obj->Name
164
165           See "Access to the name" in Mail::Message::Field
166
167       $obj->name
168
169           See "Access to the name" in Mail::Message::Field
170
171       $obj->wellformedName([STRING])
172
173           See "Access to the name" in Mail::Message::Field
174
175       Access to the body
176
177       $obj->body
178
179           See "Access to the body" in Mail::Message::Field
180
181       $obj->decodedBody(OPTIONS)
182
183           See "Access to the body" in Mail::Message::Field::Full
184
185       $obj->folded
186
187           See "Access to the body" in Mail::Message::Field
188
189       $obj->foldedBody([BODY])
190
191           See "Access to the body" in Mail::Message::Field
192
193       $obj->stripCFWS([STRING])
194
195       Mail::Message::Field::Structured->stripCFWS([STRING])
196
197           See "Access to the body" in Mail::Message::Field
198
199       $obj->unfoldedBody([BODY, [WRAP]])
200
201           See "Access to the body" in Mail::Message::Field
202
203       Access to the content
204
205       $obj->addresses
206
207           See "Access to the content" in Mail::Message::Field
208
209       $obj->attribute(OBJECT⎪(STRING, OPTIONS)⎪(NAME,VALUE,OPTIONS))
210
211           Add an attribute to the field.  The attributes are added left-to-
212           right into the string representation of the field, although the
213           order of the attributes is un-important, according to the RFCs.
214
215           You may pass a fully prepared Mail::Message::Field::Attribute
216           OBJECT, if you like to do all preparations for correct representa‐
217           tion of the data yourself.  You may also pass one STRING, which is
218           a fully prepared attribute.  This STRING will not be changed, so be
219           careful about quoting and encodings.
220
221           As third possibility, you can specify an attribute NAME and its
222           VALUE.  An attribute object will be created for you implicitly in
223           both cases where such object is not supplied, passing the OPTIONS.
224           See Mail::Message::Field::Attribute::new() about the available
225           OPTIONS.
226
227           The attribute object is returned, however, when continuations are
228           used this may be an object you already know about.  "undef" is
229           returned when construction fails (when the attribute is incorrect).
230
231           Example:
232
233            $f->attribute(filename => 'passwd');
234            $f->attribute(filename => 'passwd', use_continuations => 0);
235
236            my $attr = Mail::Message::Field::Attribute->new(...);
237            $f->attribute($attr);
238
239       $obj->attributes
240
241           Returns a list with all attributes, which are all Mail::Mes‐
242           sage::Field::Attribute objects.  The attributes are not ordered in
243           any way.  The list may be empty.  Double attributes or continua‐
244           tions are folded into one.
245
246       $obj->beautify
247
248           See "Access to the content" in Mail::Message::Field::Full
249
250       $obj->comment([STRING])
251
252           See "Access to the content" in Mail::Message::Field
253
254       $obj->createComment(STRING, OPTIONS)
255
256       Mail::Message::Field::Structured->createComment(STRING, OPTIONS)
257
258           See "Access to the content" in Mail::Message::Field::Full
259
260       $obj->createPhrase(STRING, OPTIONS)
261
262       Mail::Message::Field::Structured->createPhrase(STRING, OPTIONS)
263
264           See "Access to the content" in Mail::Message::Field::Full
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::Structured->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::Structured->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::Structured->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::Structured->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->consumeComment(STRING)
329
330       Mail::Message::Field::Structured->consumeComment(STRING)
331
332           See "Parsing" in Mail::Message::Field::Full
333
334       $obj->consumeDotAtom(STRING)
335
336           See "Parsing" in Mail::Message::Field::Full
337
338       $obj->consumePhrase(STRING)
339
340       Mail::Message::Field::Structured->consumePhrase(STRING)
341
342           See "Parsing" in Mail::Message::Field::Full
343
344       $obj->datum([VALUE])
345
346           Equivalent to body(), but maybe less confusing.
347
348       $obj->parse(STRING)
349
350           See "Parsing" in Mail::Message::Field::Full
351
352       $obj->produceBody
353
354           See "Parsing" in Mail::Message::Field::Full
355
356       Error handling
357
358       $obj->AUTOLOAD
359
360           See "Error handling" in Mail::Reporter
361
362       $obj->addReport(OBJECT)
363
364           See "Error handling" in Mail::Reporter
365
366       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
367
368       Mail::Message::Field::Structured->defaultTrace([LEVEL]⎪[LOGLEVEL,
369       TRACELEVEL]⎪[LEVEL, CALLBACK])
370
371           See "Error handling" in Mail::Reporter
372
373       $obj->errors
374
375           See "Error handling" in Mail::Reporter
376
377       $obj->log([LEVEL [,STRINGS]])
378
379       Mail::Message::Field::Structured->log([LEVEL [,STRINGS]])
380
381           See "Error handling" in Mail::Reporter
382
383       $obj->logPriority(LEVEL)
384
385       Mail::Message::Field::Structured->logPriority(LEVEL)
386
387           See "Error handling" in Mail::Reporter
388
389       $obj->logSettings
390
391           See "Error handling" in Mail::Reporter
392
393       $obj->notImplemented
394
395           See "Error handling" in Mail::Reporter
396
397       $obj->report([LEVEL])
398
399           See "Error handling" in Mail::Reporter
400
401       $obj->reportAll([LEVEL])
402
403           See "Error handling" in Mail::Reporter
404
405       $obj->trace([LEVEL])
406
407           See "Error handling" in Mail::Reporter
408
409       $obj->warnings
410
411           See "Error handling" in Mail::Reporter
412
413       Cleanup
414
415       $obj->DESTROY
416
417           See "Cleanup" in Mail::Reporter
418
419       $obj->inGlobalDestruction
420
421           See "Cleanup" in Mail::Reporter
422

DETAILS

DIAGNOSTICS

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

LICENSE

468       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
469       ChangeLog.
470
471       This program is free software; you can redistribute it and/or modify it
472       under the same terms as Perl itself.  See
473       http://www.perl.com/perl/misc/Artistic.html
474
475
476
477perl v5.8.8                       2007-03-25Mail::Message::Field::Structured(3)