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

1Mail::Message::Field::FUuslelr(3C)ontributed Perl DocumeMnatialt:i:oMnessage::Field::Full(3)
2
3
4

NAME

6       Mail::Message::Field::Full - construct one smart line in a message
7       header
8

INHERITANCE

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

SYNOPSIS

19        !! UNDER CONSTRUCTION
20        !! The details of this module are NOT FINISHED yet
21        !! Most parts are already usable, however.  With care!
22
23        # Getting to understand the complexity of a header field ...
24
25        my $fast = $msg->head->get('subject');
26        my $full = Mail::Message::Field::Full->from($fast);
27
28        my $full = $msg->head->get('subject')->study;  # same
29        my $full = $msg->head->study('subject');       # same
30        my $full = $msg->get('subject');               # same
31
32        # ... or build a complex header field yourself
33
34        my $f = Mail::Message::Field::Full->new('To');
35        my $f = Mail::Message::Field::Full->new('Subject: hi!');
36        my $f = Mail::Message::Field::Full->new(Subject => 'hi!');
37

DESCRIPTION

39       This is the full implementation of a header field: it has full under‐
40       standing of all predefined header fields.  These objects will be quite
41       slow, because header fields can be very complex.  Of course, this class
42       delivers the optimal result, but for a quite large penalty in perfor‐
43       mance and memory consumption.  Are you willing to accept?
44
45       This class supports the common header description from RFC2822 (for‐
46       merly RFC822), the extensions with respect to character set encodings
47       as specified in RFC2047, and the extensions on language specification
48       and long parameter wrapping from RFC2231.  If you do not need the lat‐
49       ter two, then the Mail::Message::Field::Fast and Mail::Mes‐
50       sage::Field::Flex are enough for your application.
51

OVERLOADED

53       overload: ""
54
55           See "OVERLOADED" in Mail::Message::Field
56
57       overload: +0
58
59           See "OVERLOADED" in Mail::Message::Field
60
61       overload: <=>
62
63           See "OVERLOADED" in Mail::Message::Field
64
65       overload: bool
66
67           See "OVERLOADED" in Mail::Message::Field
68
69       overload: cmp
70
71           See "OVERLOADED" in Mail::Message::Field
72
73       overload: stringification
74
75           In string context, the decoded body is returned, as if decoded‐
76           Body() would have been called.
77

METHODS

79       Constructors
80
81       $obj->clone
82
83           See "Constructors" in Mail::Message::Field
84
85       Mail::Message::Field::Full->from(FIELD, OPTIONS)
86
87           Convert any FIELD (a Mail::Message::Field object) into a new
88           Mail::Message::Field::Full object.  This conversion is done the
89           hard way: the string which is produced by the original object is
90           parsed again.  Usually, the string which is parsed is exactly the
91           line (or lines) as found in the original input source, which is a
92           good thing because Full fields are much more carefull with the
93           actual content.
94
95           OPTIONS are passed to the constructor (see new()).  In any case,
96           some extensions of this Full field class is returned.  It depends
97           on which field is created what kind of class we get.
98
99           Example:
100
101            my $fast = $msg->head->get('subject');
102            my $full = Mail::Message::Field::Full->from($fast);
103
104            my $full = $msg->head->get('subject')->study;  # same
105            my $full = $msg->head->study('subject');       # same
106            my $full = $msg->get('subject');               # same
107
108       Mail::Message::Field::Full->new(DATA)
109
110           Creating a new field object the correct way is a lot of work,
111           because there is so much freedom in the RFCs, but at the same time
112           so many restrictions.  Most fields are implemented, but if you have
113           your own field (and do no want to contribute it to MailBox), then
114           simply call new on your own package.
115
116           You have the choice to instantiate the object as string or in pre‐
117           pared parts:
118
119           * new LINE, OPTIONS
120               Pass a LINE as it could be found in a file: a (possibly folded)
121               line which is terminated by a new-line.
122
123           * new NAME, [BODY], OPTIONS
124               A set of values which shape the line.
125
126           The NAME is a wellformed header name (you may use wellformedName())
127           to be sure about the casing.  The BODY is a string, one object, or
128           an ref-array of objects.  In case of objects, they must fit to the
129           constructor of the field: the types which are accepted may differ.
130           The optional ATTRIBUTE list contains Mail::Mes‐
131           sage::Field::Attribute objects.  Finally, there are some OPTIONS.
132
133            Option  --Defined in     --Default
134            charset                    undef
135            encoding                   'q'
136            force                      false
137            language                   undef
138            log       Mail::Reporter   'WARNINGS'
139            trace     Mail::Reporter   'WARNINGS'
140
141           . charset STRING
142
143               The body is specified in utf8, and must become 7-bits ascii to
144               be transmited.  Specify a charset to which the multi-byte utf8
145               is converted before it gets encoded.  See encode(), which does
146               the job.
147
148           . encoding 'q'⎪'Q'⎪'b'⎪'B'
149
150               Non-ascii characters are encoded using Quoted-Printable ('q' or
151               'Q') or Base64 ('b' or 'B') encoding.
152
153           . force BOOLEAN
154
155               Enforce encoding in the specified charset, even when it is not
156               needed because the body does not contain any non-ascii charac‐
157               ters.
158
159           . language STRING
160
161               The language used can be specified, however is rarely used my
162               mail clients.
163
164           . log LEVEL
165
166           . trace LEVEL
167
168           Example:
169
170            my $s = Mail::Message::Field::Full->new('Subject: Hello World');
171            my $s = Mail::Message::Field::Full->new('Subject', 'Hello World');
172
173            my @attrs   = (Mail::Message::Field::Attribute->new(...), ...);
174            my @options = (extra => 'the color blue');
175            my $t = Mail::Message::Field::Full->new(To => \@addrs, @attrs, @options);
176
177       The field
178
179       $obj->isStructured
180
181       Mail::Message::Field::Full->isStructured
182
183           See "The field" in Mail::Message::Field
184
185       $obj->length
186
187           See "The field" in Mail::Message::Field
188
189       $obj->nrLines
190
191           See "The field" in Mail::Message::Field
192
193       $obj->print([FILEHANDLE])
194
195           See "The field" in Mail::Message::Field
196
197       $obj->size
198
199           See "The field" in Mail::Message::Field
200
201       $obj->string([WRAP])
202
203           See "The field" in Mail::Message::Field
204
205       $obj->toDisclose
206
207           See "The field" in Mail::Message::Field
208
209       Access to the name
210
211       $obj->Name
212
213           See "Access to the name" in Mail::Message::Field
214
215       $obj->name
216
217           See "Access to the name" in Mail::Message::Field
218
219       $obj->wellformedName([STRING])
220
221           See "Access to the name" in Mail::Message::Field
222
223       Access to the body
224
225       $obj->body
226
227           See "Access to the body" in Mail::Message::Field
228
229       $obj->decodedBody(OPTIONS)
230
231           Returns the unfolded body of the field, where encodings are
232           resolved.  The returned line will still contain comments and such.
233           The OPTIONS are passed to the decoder, see decode().
234
235           BE WARNED: if the field is a structured field, the content may
236           change syntax, because of encapsulated special characters.  By
237           default, the body is decoded as text, which results in a small dif‐
238           ference within comments as well (read the RFC).
239
240       $obj->folded
241
242           See "Access to the body" in Mail::Message::Field
243
244       $obj->foldedBody([BODY])
245
246           See "Access to the body" in Mail::Message::Field
247
248       $obj->stripCFWS([STRING])
249
250       Mail::Message::Field::Full->stripCFWS([STRING])
251
252           See "Access to the body" in Mail::Message::Field
253
254       $obj->unfoldedBody([BODY, [WRAP]])
255
256           See "Access to the body" in Mail::Message::Field
257
258       Access to the content
259
260       $obj->addresses
261
262           See "Access to the content" in Mail::Message::Field
263
264       $obj->attribute(NAME [, VALUE])
265
266           See "Access to the content" in Mail::Message::Field
267
268       $obj->attributes
269
270           See "Access to the content" in Mail::Message::Field
271
272       $obj->beautify
273
274           For structured header fields, this removes the original encoding of
275           the field's body (the format as it was offered to parse()), there‐
276           fore the next request for the field will have to re-produce the
277           read data clean and nice.  For unstructured bodies, this method
278           doesn't do a thing.
279
280       $obj->comment([STRING])
281
282           See "Access to the content" in Mail::Message::Field
283
284       $obj->createComment(STRING, OPTIONS)
285
286       Mail::Message::Field::Full->createComment(STRING, OPTIONS)
287
288           Create a comment to become part in a field.  Comments are automati‐
289           cally included within parenthesis.  Matching pairs of parenthesis
290           are permitted within the STRING.  When a non-matching parenthesis
291           are used, it is only permitted with an escape (a backslash) in
292           front of them.  These backslashes will be added automatically if
293           needed (don't worry!).  Backslashes will stay, except at the end,
294           where it will be doubled.
295
296           The OPTIONS are "charset", "language", and "encoding" as always.
297           The created comment is returned.
298
299       $obj->createPhrase(STRING, OPTIONS)
300
301       Mail::Message::Field::Full->createPhrase(STRING, OPTIONS)
302
303           A phrase is a text which plays a well defined role.  This is the
304           main difference with comments, which have do specified meaning.
305           Some special characters in the phrase will cause it to be sur‐
306           rounded with double quotes: do not specify them yourself.
307
308           The OPTIONS are "charset", "language", and "encoding" as always.
309
310       $obj->study
311
312           See "Access to the content" in Mail::Message::Field
313
314       $obj->toDate([TIME])
315
316       Mail::Message::Field::Full->toDate([TIME])
317
318           See "Access to the content" in Mail::Message::Field
319
320       $obj->toInt
321
322           See "Access to the content" in Mail::Message::Field
323
324       Other methods
325
326       $obj->dateToTimestamp(STRING)
327
328       Mail::Message::Field::Full->dateToTimestamp(STRING)
329
330           See "Other methods" in Mail::Message::Field
331
332       Internals
333
334       $obj->consume(LINE ⎪ (NAME,BODY⎪OBJECTS))
335
336           See "Internals" in Mail::Message::Field
337
338       $obj->decode(STRING, OPTIONS)
339
340       Mail::Message::Field::Full->decode(STRING, OPTIONS)
341
342           Decode field encoded STRING to an utf8 string.  The input STRING is
343           part of a header field, and as such, may contain encoded words in
344           "=?...?.?...?=" format defined by RFC2047.  The STRING may contain
345           multiple encoded parts, maybe using different character sets.
346
347           Be warned:  you MUST first interpret the field into parts, like
348           phrases and comments, and then decode each part separately, other‐
349           wise the decoded text may interfere with your markup characters.
350
351           Be warned: language information, which is defined in RFC2231, is
352           ignored.
353
354            Option --Default
355            is_text  1
356
357           . is_text BOOLEAN
358
359               Encoding on text is slightly more complicated than encoding
360               structured data, because it contains blanks.  Visible blanks
361               have to be ignored between two encoded words in the text, but
362               not when an encoded word follows or preceeds an unencoded word.
363               Phrases and comments are texts.
364
365           Example:
366
367            print Mail::Message::Field::Full->decode('=?iso-8859-1?Q?J=F8rgen?=');
368               # prints   JE<0slash>rgen
369
370       $obj->defaultWrapLength([LENGTH])
371
372           See "Internals" in Mail::Message::Field
373
374       $obj->encode(STRING, OPTIONS)
375
376           Encode the (possibly utf8 encoded) STRING to a string which is
377           acceptable to the RFC2047 definition of a header: only containing
378           us-ascii characters.
379
380            Option  --Default
381            charset   'us-ascii'
382            encoding  'q'
383            force     <flase>
384            language  undef
385
386           . charset STRING
387
388               STRING is an utf8 string which has to be translated into any
389               byte-wise character set for transport, because MIME-headers can
390               only contain ascii characters.
391
392           . encoding 'q'⎪'Q'⎪'b'⎪'B'
393
394               The character encoding to be used.  With "q" or "Q", quoted-
395               printable encoding will be used.  With "b " or "B ", base64
396               encoding will be taken.
397
398           . force BOOLEAN
399
400               Encode the string, even when it only contains us-ascii charac‐
401               ters.  By default, this is off because it decreases readibility
402               of the produced header fields.
403
404           . language STRING
405
406               RFC2231 defines how to specify language encodings in encoded
407               words.  The STRING is a strandard iso language name.
408
409       $obj->fold(NAME, BODY, [MAXCHARS])
410
411       Mail::Message::Field::Full->fold(NAME, BODY, [MAXCHARS])
412
413           See "Internals" in Mail::Message::Field
414
415       $obj->setWrapLength([LENGTH])
416
417           See "Internals" in Mail::Message::Field
418
419       $obj->stringifyData(STRING⎪ARRAY⎪OBJECTS)
420
421           See "Internals" in Mail::Message::Field
422
423       $obj->unfold(STRING)
424
425           See "Internals" in Mail::Message::Field
426
427       Parsing
428
429       $obj->consumeComment(STRING)
430
431       Mail::Message::Field::Full->consumeComment(STRING)
432
433           Try to read a comment from the STRING.  When successful, the com‐
434           ment without encapsulation parenthesis is returned, together with
435           the rest of the string.
436
437       $obj->consumeDotAtom(STRING)
438
439           Returns three elemens: the atom-text, the rest string, and the con‐
440           catenated comments.  Both atom and comments can be undef.
441
442       $obj->consumePhrase(STRING)
443
444       Mail::Message::Field::Full->consumePhrase(STRING)
445
446           Take the STRING, and try to strip-off a valid phrase.  In the obso‐
447           lete phrase syntax, any sequence of words is accepted as phrase (as
448           long as certain special characters are not used).  RFC2882 is
449           stricter: only one word or a quoted string is allowed.  As always,
450           the obsolete syntax is accepted, and the new syntax is produced.
451
452           This method returns two elements: the phrase (or undef) followed by
453           the resulting string.  The phrase will be removed from the optional
454           quotes.  Be warned that "" will return an empty, valid phrase.
455
456           Example:
457
458            my ($phrase, $rest) = $field->consumePhrase( q["hi!" <sales@example.com>] );
459
460       $obj->parse(STRING)
461
462           Get the detailed information from the STRING, and store the data
463           found in the field object.  The accepted input is very field type
464           dependent.  Unstructured fields do no parsing whatsoever.
465
466       $obj->produceBody
467
468           Produce the text for the field, based on the information stored
469           within the field object.
470
471           Usually, you wish the exact same line as was found in the input
472           source of a message.  But when you have created a field yourself,
473           it should get formatted.  You may call beautify() on a preformatted
474           field to enforce a call to this method when the field is needed
475           later.
476
477       Error handling
478
479       $obj->AUTOLOAD
480
481           See "Error handling" in Mail::Reporter
482
483       $obj->addReport(OBJECT)
484
485           See "Error handling" in Mail::Reporter
486
487       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
488
489       Mail::Message::Field::Full->defaultTrace([LEVEL]⎪[LOGLEVEL,
490       TRACELEVEL]⎪[LEVEL, CALLBACK])
491
492           See "Error handling" in Mail::Reporter
493
494       $obj->errors
495
496           See "Error handling" in Mail::Reporter
497
498       $obj->log([LEVEL [,STRINGS]])
499
500       Mail::Message::Field::Full->log([LEVEL [,STRINGS]])
501
502           See "Error handling" in Mail::Reporter
503
504       $obj->logPriority(LEVEL)
505
506       Mail::Message::Field::Full->logPriority(LEVEL)
507
508           See "Error handling" in Mail::Reporter
509
510       $obj->logSettings
511
512           See "Error handling" in Mail::Reporter
513
514       $obj->notImplemented
515
516           See "Error handling" in Mail::Reporter
517
518       $obj->report([LEVEL])
519
520           See "Error handling" in Mail::Reporter
521
522       $obj->reportAll([LEVEL])
523
524           See "Error handling" in Mail::Reporter
525
526       $obj->trace([LEVEL])
527
528           See "Error handling" in Mail::Reporter
529
530       $obj->warnings
531
532           See "Error handling" in Mail::Reporter
533
534       Cleanup
535
536       $obj->DESTROY
537
538           See "Cleanup" in Mail::Reporter
539
540       $obj->inGlobalDestruction
541
542           See "Cleanup" in Mail::Reporter
543

DETAILS

DIAGNOSTICS

546       Warning: Field content is not numerical: $content
547
548       The numeric value of a field is requested (for instance the "Lines" or
549       "Content-Length" fields should be numerical), however the data contains
550       weird characters.
551
552       Warning: Illegal character in charset '$charset'
553
554       The field is created with an utf8 string which only contains data from
555       the specified character set.  However, that character set can never be
556       a valid name because it contains characters which are not permitted.
557
558       Warning: Illegal character in field name $name
559
560       A new field is being created which does contain characters not permit‐
561       ted by the RFCs.  Using this field in messages may break other e-mail
562       clients or transfer agents, and therefore mutulate or extinguish your
563       message.
564
565       Warning: Illegal character in language '$lang'
566
567       The field is created with data which is specified to be in a certain
568       language, however, the name of the language cannot be valid: it con‐
569       tains characters which are not permitted by the RFCs.
570
571       Warning: Illegal encoding '$encoding', used 'q'
572
573       The RFCs only permit base64 ("b " or "B ") or quoted-printable ("q" or
574       "Q") encoding.  Other than these four options are illegal.
575
576       Error: Package $package does not implement $method.
577
578       Fatal error: the specific package (or one of its superclasses) does not
579       implement this method where it should. This message means that some
580       other related classes do implement this method however the class at
581       hand does not.  Probably you should investigate this and probably
582       inform the author of the package.
583

LICENSE

589       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
590       ChangeLog.
591
592       This program is free software; you can redistribute it and/or modify it
593       under the same terms as Perl itself.  See
594       http://www.perl.com/perl/misc/Artistic.html
595
596
597
598perl v5.8.8                       2007-03-25     Mail::Message::Field::Full(3)