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        # Getting to understand the complexity of a header field ...
20
21        my $fast = $msg->head->get('subject');
22        my $full = Mail::Message::Field::Full->from($fast);
23
24        my $full = $msg->head->get('subject')->study;  # same
25        my $full = $msg->head->study('subject');       # same
26        my $full = $msg->study('subject');             # same
27
28        # ... or build a complex header field yourself
29
30        my $f = Mail::Message::Field::Full->new('To');
31        my $f = Mail::Message::Field::Full->new('Subject: hi!');
32        my $f = Mail::Message::Field::Full->new(Subject => 'hi!');
33

DESCRIPTION

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

OVERLOADED

51       Extends "OVERLOADED" in Mail::Message::Field.
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           In string context, the decoded body is returned, as if
70           decodedBody() would have been called.
71

METHODS

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

DETAILS

483       Extends "DETAILS" in Mail::Message::Field.
484

DIAGNOSTICS

486       Warning: Field content is not numerical: $content
487           The numeric value of a field is requested (for instance the "Lines"
488           or "Content-Length" fields should be numerical), however the data
489           contains weird characters.
490
491       Warning: Illegal character in charset '$charset'
492           The field is created with an utf8 string which only contains data
493           from the specified character set.  However, that character set can
494           never be a valid name because it contains characters which are not
495           permitted.
496
497       Warning: Illegal character in field name $name
498           A new field is being created which does contain characters not
499           permitted by the RFCs.  Using this field in messages may break
500           other e-mail clients or transfer agents, and therefore mutulate or
501           extinguish your message.
502
503       Warning: Illegal character in language '$lang'
504           The field is created with data which is specified to be in a
505           certain language, however, the name of the language cannot be
506           valid: it contains characters which are not permitted by the RFCs.
507
508       Warning: Illegal encoding '$encoding', used 'q'
509           The RFCs only permit base64 ("b " or "B ") or quoted-printable ("q"
510           or "Q") encoding.  Other than these four options are illegal.
511
512       Error: Package $package does not implement $method.
513           Fatal error: the specific package (or one of its superclasses) does
514           not implement this method where it should. This message means that
515           some other related classes do implement this method however the
516           class at hand does not.  Probably you should investigate this and
517           probably inform the author of the package.
518

LICENSE

524       Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
525       contributors see ChangeLog.
526
527       This program is free software; you can redistribute it and/or modify it
528       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
529
530
531
532perl v5.36.0                      2023-01-20     Mail::Message::Field::Full(3)