1Mail::Message::Field(3)User Contributed Perl DocumentatioMnail::Message::Field(3)
2
3
4

NAME

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

INHERITANCE

9        Mail::Message::Field
10          is a Mail::Reporter
11
12        Mail::Message::Field is extended by
13          Mail::Message::Field::Fast
14          Mail::Message::Field::Flex
15          Mail::Message::Field::Full
16

SYNOPSIS

18        my $field = Mail::Message::Field->new(From => 'fish@tux.aq');
19        print $field->name;
20        print $field->body;
21        print $field->comment;
22        print $field->content;  # body & comment
23        $field->print(\*OUT);
24        print $field->string;
25        print "$field\n";
26        print $field->attribute('charset') || 'us-ascii';
27

DESCRIPTION

29       This implementation follows the guidelines of rfc2822 as close as
30       possible, and may there produce a different output than implementations
31       based on the obsolete rfc822.  However, the old output will still be
32       accepted.
33
34       These objects each store one header line, and facilitates access
35       routines to the information hidden in it.  Also, you may want to have a
36       look at the added methods of a message:
37
38        my @from    = $message->from;
39        my $sender  = $message->sender;
40        my $subject = $message->subject;
41        my $msgid   = $message->messageId;
42
43        my @to      = $message->to;
44        my @cc      = $message->cc;
45        my @bcc     = $message->bcc;
46        my @dest    = $message->destinations;
47
48        my $other   = $message->get('Reply-To');
49
50       Extends "DESCRIPTION" in Mail::Reporter.
51

OVERLOADED

53       overload: ""
54           (stringification) produces the unfolded body of the field, which
55           may be what you expect.  This is what makes what the field object
56           seems to be a simple string. The string is produced by
57           unfoldedBody().
58
59           example:
60
61            print $msg->get('subject');  # via overloading
62            print $msg->get('subject')->unfoldedBody; # same
63
64            my $subject = $msg->get('subject') || 'your mail';
65            print "Re: $subject\n";
66
67       overload: 0+
68           (numification) When the field is numeric, the value will be
69           returned.  The result is produced by toInt().  If the value is not
70           correct, a 0 is produced, to simplify calculations.
71
72       overload: <=>
73           (numeric comparison) Compare the integer field contents with
74           something else.
75
76           example:
77
78            if($msg->get('Content-Length') > 10000) ...
79            if($msg->size > 10000) ... ; # same, but better
80
81       overload: bool
82           Always true, to make it possible to say "if($field)".
83
84       overload: cmp
85           (string comparison) Compare the unfolded body of a field with
86           another field or a string, using the buildin "cmp".
87

METHODS

89       Extends "METHODS" in Mail::Reporter.
90
91   Constructors
92       Extends "Constructors" in Mail::Reporter.
93
94       $obj->clone()
95           Create a copy of this field object.
96
97       Mail::Message::Field->new($data)
98           See Mail::Message::Field::Fast::new(),
99           Mail::Message::Field::Flex::new(), and
100           Mail::Message::Field::Full::new().  By default, a "Fast" field is
101           produced.
102
103            -Option--Defined in     --Default
104             log     Mail::Reporter   'WARNINGS'
105             trace   Mail::Reporter   'WARNINGS'
106
107           log => LEVEL
108           trace => LEVEL
109
110   The field
111       $obj->isStructured()
112       Mail::Message::Field->isStructured()
113           Some fields are described in the RFCs as being structured: having a
114           well described syntax.  These fields have common ideas about
115           comments and the like, what they do not share with unstructured
116           fields, like the "Subject" field.
117
118           example:
119
120            my $field = Mail::Message::Field->new(From => 'me');
121            if($field->isStructured)
122
123            Mail::Message::Field->isStructured('From');
124
125       $obj->length()
126           Returns the total length of the field in characters, which includes
127           the field's name, body and folding characters.
128
129       $obj->nrLines()
130           Returns the number of lines needed to display this header-line.
131
132       $obj->print( [$fh] )
133           Print the whole header-line to the specified file-handle. One line
134           may result in more than one printed line, because of the folding of
135           long lines.  The $fh defaults to the selected handle.
136
137       $obj->size()
138           Returns the number of bytes needed to display this header-line,
139           Same as length().
140
141       $obj->string( [$wrap] )
142           Returns the field as string.  By default, this returns the same as
143           folded(). However, the optional $wrap will cause to re-fold to take
144           place (without changing the folding stored inside the field).
145
146       $obj->toDisclose()
147           Returns whether this field can be disclosed to other people, for
148           instance when sending the message to another party.  Returns a
149           "true" or "false" condition.  See also
150           Mail::Message::Head::Complete::printUndisclosed().
151
152   Access to the name
153       $obj->Name()
154           Returns the name of this field in original casing.  See name() as
155           well.
156
157       $obj->name()
158           Returns the name of this field, with all characters lower-cased for
159           ease of comparison.  See Name() as well.
160
161       $obj->wellformedName( [STRING] )
162           (Instance method class method) As instance method, the current
163           field's name is correctly formatted and returned.  When a STRING is
164           used, that one is formatted.
165
166           example:
167
168            print Mail::Message::Field->Name('content-type')
169              # -->  Content-Type
170
171            my $field = $head->get('date');
172            print $field->Name;
173              # -->  Date
174
175   Access to the body
176       $obj->body()
177           This method may be what you want, but usually, the foldedBody() and
178           unfoldedBody() are what you are looking for.  This method is
179           cultural heritage, and should be avoided.
180
181           Returns the body of the field.  When this field is structured, it
182           will be stripped from everything what is behind the first semi-
183           color (";").  In any case, the string is unfolded.  Whether the
184           field is structured is defined by isStructured().
185
186       $obj->folded()
187           Returns the folded version of the whole header.  When the header is
188           shorter than the wrap length, a list of one line is returned.
189           Otherwise more lines will be returned, all but the first starting
190           with at least one blank.  See also foldedBody() to get the same
191           information without the field's name.
192
193           In scalar context, the lines are delived into one string, which is
194           a little faster because that's the way they are stored
195           internally...
196
197           example:
198
199            my @lines = $field->folded;
200            print $field->folded;
201            print scalar $field->folded; # faster
202
203       $obj->foldedBody( [$body] )
204           Returns the body as a set of lines. In scalar context, this will be
205           one line containing newlines.  Be warned about the newlines when
206           you do pattern matching on the result of this method.
207
208           The optional $body argument changes the field's body.  The folding
209           of the argument must be correct.
210
211       $obj->stripCFWS( [STRING] )
212       Mail::Message::Field->stripCFWS( [STRING] )
213           Remove the comments and folding white spaces from the STRING.
214           Without string and only as instance method, the unfoldedBody() is
215           being stripped and returned.
216
217           WARNING: This operation is only allowed for structured header
218           fields (which are defined by the various RFCs as being so.  You
219           don't want parts within braces which are in the Subject header line
220           to be removed, to give an example.
221
222       $obj->unfoldedBody( [$body, [$wrap]] )
223           Returns the body as one single line, where all folding information
224           (if available) is removed.  This line will also NOT end on a new-
225           line.
226
227           The optional $body argument changes the field's body.  The right
228           folding is performed before assignment.  The $wrap may be specified
229           to enforce a folding size.
230
231           example:
232
233            my $body = $field->unfoldedBody;
234            print "$field";   # via overloading
235
236   Access to the content
237       $obj->addresses()
238           Returns a list of Mail::Address objects, which represent the e-mail
239           addresses found in this header line.
240
241           example:
242
243            my @addr = $message->head->get('to')->addresses;
244            my @addr = $message->to;
245
246       $obj->attribute( $name, [$value] )
247           Get the value of an attribute, optionally after setting it to a new
248           value.  Attributes are part of some header lines, and hide
249           themselves in the comment field.  If the attribute does not exist,
250           then "undef" is returned.  The attribute is still encoded.
251
252           example:
253
254            my $field = Mail::Message::Field->new(
255             'Content-Type: text/plain; charset="us-ascii"');
256
257            print $field->attribute('charset');
258              # --> us-ascii
259
260            print $field->attribute('bitmap') || 'no'
261              # --> no
262
263            $field->atrribute(filename => '/tmp/xyz');
264            $field->print;
265              # --> Content-Type: text/plain; charset="us-ascii";
266              #       filename="/tmp/xyz"
267              # Automatically folded, and no doubles created.
268
269       $obj->attributes()
270           Returns a list of key-value pairs, where the values are not yet
271           decoded.  Keys may appear more than once.
272
273           example:
274
275            my @pairs = $head->get('Content-Disposition')->attributes;
276
277       $obj->comment( [STRING] )
278           Returns the unfolded comment (part after a semi-colon) in a
279           structureed header-line. optionally after setting it to a new
280           STRING first.  When "undef" is specified as STRING, the comment is
281           removed.  Whether the field is structured is defined by
282           isStructured().
283
284           The comment part of a header field often contains "attributes".
285           Often it is preferred to use attribute() on them.
286
287       $obj->study()
288           Study the header field in detail: turn on the full parsing and
289           detailed understanding of the content of the fields.
290           Mail::Message::Field::Fast and Mail::Message::Field::Fast objects
291           will be transformed into any Mail::Message::Field::Full object.
292
293           example:
294
295            my $subject = $msg->head->get('subject')->study;
296            my $subject = $msg->head->study('subject');  # same
297            my $subject = $msg->study('subject');        # same
298
299       $obj->toDate( [$time] )
300       Mail::Message::Field->toDate( [$time] )
301           Convert a timestamp into an rfc2822 compliant date format.  This
302           differs from the default output of "localtime" in scalar context.
303           Without argument, the "localtime" is used to get the current time.
304           $time can be specified as one numeric (like the result of "time()")
305           and as list (like produced by c<localtime()> in list context).
306
307           Be sure to have your timezone set right, especially when this
308           script runs automatically.
309
310           example:
311
312            my $now = time;
313            Mail::Message::Field->toDate($now);
314            Mail::Message::Field->toDate(time);
315
316            Mail::Message::Field->toDate(localtime);
317            Mail::Message::Field->toDate;      # same
318            # returns something like:
319            #     Wed, 28 Aug 2002 10:40:25 +0200
320
321       $obj->toInt()
322           Returns the value which is related to this field as integer.  A
323           check is performed whether this is right.
324
325   Other methods
326       $obj->dateToTimestamp(STRING)
327       Mail::Message::Field->dateToTimestamp(STRING)
328           Convert a STRING which represents and RFC compliant time string
329           into a timestamp like is produced by the "time" function.
330
331   Internals
332       $obj->consume( $line | <$name,<$body|$objects>> )
333           Accepts a whole field $line, or a pair with the field's $name and
334           $body. In the latter case, the $body data may be specified as array
335           of $objects which are stringified.  Returned is a nicely formatted
336           pair of two strings: the field's name and a folded body.
337
338           This method is called by new(), and usually not by an application
339           program. The details about converting the $objects to a field
340           content are explained in "Specifying field data".
341
342       $obj->defaultWrapLength( [$length] )
343           Any field from any header for any message will have this default
344           wrapping.  This is maintained in one global variable.  Without a
345           specified $length, the current value is returned.  The default is
346           78.
347
348       $obj->fold( $name, $body, [$maxchars] )
349       Mail::Message::Field->fold( $name, $body, [$maxchars] )
350           Make the header field with $name fold into multiple lines.
351           Wrapping is performed by inserting newlines before a blanks in the
352           $body, such that no line exceeds the $maxchars and each line is as
353           long as possible.
354
355           The RFC requests for folding on nice spots, but this request is
356           mainly ignored because it would make folding too slow.
357
358       $obj->setWrapLength( [$length] )
359           Force the wrapping of this field to the specified $length
360           characters. The wrapping is performed with fold() and the results
361           stored within the field object.
362
363           example: refolding the field
364
365            $field->setWrapLength(99);
366
367       $obj->stringifyData(STRING|ARRAY|$objects)
368           This method implements the translation of user supplied objects
369           into ascii fields.  The process is explained in "Specifying field
370           data".
371
372       $obj->unfold(STRING)
373           The reverse action of fold(): all lines which form the body of a
374           field are joined into one by removing all line terminators (even
375           the last).  Possible leading blanks on the first line are removed
376           as well.
377
378   Error handling
379       Extends "Error handling" in Mail::Reporter.
380
381       $obj->AUTOLOAD()
382           Inherited, see "Error handling" in Mail::Reporter
383
384       $obj->addReport($object)
385           Inherited, see "Error handling" in Mail::Reporter
386
387       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
388       $callback] )
389       Mail::Message::Field->defaultTrace( [$level]|[$loglevel,
390       $tracelevel]|[$level, $callback] )
391           Inherited, see "Error handling" in Mail::Reporter
392
393       $obj->errors()
394           Inherited, see "Error handling" in Mail::Reporter
395
396       $obj->log( [$level, [$strings]] )
397       Mail::Message::Field->log( [$level, [$strings]] )
398           Inherited, see "Error handling" in Mail::Reporter
399
400       $obj->logPriority($level)
401       Mail::Message::Field->logPriority($level)
402           Inherited, see "Error handling" in Mail::Reporter
403
404       $obj->logSettings()
405           Inherited, see "Error handling" in Mail::Reporter
406
407       $obj->notImplemented()
408           Inherited, see "Error handling" in Mail::Reporter
409
410       $obj->report( [$level] )
411           Inherited, see "Error handling" in Mail::Reporter
412
413       $obj->reportAll( [$level] )
414           Inherited, see "Error handling" in Mail::Reporter
415
416       $obj->trace( [$level] )
417           Inherited, see "Error handling" in Mail::Reporter
418
419       $obj->warnings()
420           Inherited, see "Error handling" in Mail::Reporter
421
422   Cleanup
423       Extends "Cleanup" in Mail::Reporter.
424
425       $obj->DESTROY()
426           Inherited, see "Cleanup" in Mail::Reporter
427

DETAILS

429   Field syntax
430       Fields are stored in the header of a message, which are represented by
431       Mail::Message::Head objects. A field is a combination of a name, body,
432       and attributes.  Especially the term "body" is cause for confusion:
433       sometimes the attributes are considered to be part of the body.
434
435       The name of the field is followed by a colon ("":"", not preceded by
436       blanks, but followed by one blank).  Each attribute is preceded by a
437       separate semi-colon ("";"").  Names of fields are case-insensitive and
438       cannot contain blanks.
439
440       . Example: of fields
441
442       Correct fields:
443
444        Field: hi!
445        Content-Type: text/html; charset=latin1
446
447       Incorrect fields, but accepted:
448
449        Field : wrong, blank before colon
450        Field:                 # wrong, empty
451        Field:not nice, blank preferred after colon
452        One Two: wrong, blank in name
453
454       Folding fields
455
456       Fields which are long can be folded to span more than one line.  The
457       real limit for lines in messages is only at 998 characters, however
458       such long lines are not easy to read without support of an application.
459       Therefore rfc2822 (which defines the message syntax) specifies
460       explicitly that field lines can be re-formatted into multiple sorter
461       lines without change of meaning, by adding new-line characters to any
462       field before any blank or tab.
463
464       Usually, the lines are reformatted to create lines which are 78
465       characters maximum. Some applications try harder to fold on nice spots,
466       like before attributes.  Especially the "Received" field is often
467       manually folded into some nice layout.  In most cases however, it is
468       preferred to produce lines which are as long as possible but max 78.
469
470       BE WARNED that all fields can be subjected to folding, and that you
471       usually want the unfolded value.
472
473       . Example: of field folding
474
475        Subject: this is a short line, and not folded
476
477        Subject: this subject field is much longer, and therefore
478         folded into multiple
479         lines, although one more than needed.
480
481       Structured fields
482
483       The rfc2822 describes a large number of header fields explicitly.
484       These fields have a defined meaning.  For some of the fields, like the
485       "Subject" field, the meaning is straight forward the contents itself.
486       These fields are the Unstructured Fields.
487
488       Other fields have a well defined internal syntax because their content
489       is needed by e-mail applications. For instance, the "To" field contains
490       addresses which must be understood by all applications in the same way.
491       These are the Structured Fields, see isStructured().
492
493       Comments in fields
494
495       Stuctured fields can contain comments, which are pieces of text
496       enclosed in parenthesis.  These comments can be placed close to
497       anywhere in the line and must be ignored be the application.  Not all
498       applications are capable of handling comments correctly in all
499       circumstances.
500
501       . Example: of field comments
502
503        To: mailbox (Mail::Box mailinglist) <mailbox@overmeer.net>
504        Date: Thu, 13 Sep 2001 09:40:48 +0200 (CEST)
505        Subject: goodbye (was: hi!)
506
507       On the first line, the text "Mail::Box mailinglist" is used as comment.
508       Be warned that rfc2822 explicitly states that comments in e-mail
509       address specifications should not be considered to contain any usable
510       information.
511
512       On the second line, the timezone is specified as comment. The "Date"
513       field format has no way to indicate the timezone of the sender, but
514       only contains the timezone difference to UTC, however one could decide
515       to add this as comment.  Application must ignore this data because the
516       "Date" field is structured.
517
518       The last field is unstructured.  The text between parentheses is an
519       integral part of the subject line.
520
521   Getting a field
522       As many programs as there are handling e-mail, as many variations on
523       accessing the header information are requested.  Be careful which way
524       you access the data: read the variations described here and decide
525       which solution suites your needs best.
526
527       Using get() field
528
529       The "get()" interface is copied from other Perl modules which can
530       handle e-mail messages.  Many applications which simply replace
531       Mail::Internet objects by Mail::Message objects will work without
532       modification.
533
534       There is more than one get method.  The exact results depend on which
535       get you use.  When Mail::Message::get() is called, you will get the
536       unfolded, stripped from comments, stripped from attributes contents of
537       the field as string.  Character-set encodings will still be in the
538       string.  If the same fieldname appears more than once in the header,
539       only the last value is returned.
540
541       When Mail::Message::Head::get() is called in scalar context, the last
542       field with the specified name is returned as field object.  This object
543       strinigfies into the unfolded contents of the field, including
544       attributes and comments.  In list context, all appearances of the field
545       in the header are returned as objects.
546
547       BE WARNED that some lines seem unique, but are not according to the
548       official rfc.  For instance, "To" fields can appear more than once.  If
549       your program calls "get('to')" in scalar context, some information is
550       lost.
551
552       . Example: of using get()
553
554        print $msg->get('subject') || 'no subject';
555        print $msg->head->get('subject') || 'no subject';
556
557        my @to = $msg->head->get('to');
558
559       Using study() field
560
561       As the name "study" already implies, this way of accessing the fields
562       is much more thorough but also slower.  The "study" of a field is like
563       a "get", but provides easy access to the content of the field and
564       handles character-set decoding correctly.
565
566       The Mail::Message::study() method will only return the last field with
567       that name as object.  Mail::Message::Head::study() and
568       Mail::Message::Field::study() return all fields when used in list
569       context.
570
571       . Example: of using study()
572
573        print $msg->study('subject') || 'no subject';
574        my @rec  = $msg->head->study('Received');
575
576        my $from = $msg->head->get('From')->study;
577        my $from = $msg->head->study('From');  # same
578        my @addr = $from->addresses;
579
580       Using resent groups
581
582       Some fields belong together in a group of fields.  For instance, a set
583       of lines is used to define one step in the mail transport process.
584       Each step adds a "Received" line, and optionally some "Resent-*" lines
585       and "Return-Path".  These groups of lines shall stay together and in
586       order when the message header is processed.
587
588       The "Mail::Message::Head::ResentGroup" object simplifies the access to
589       these related fields.  These resent groups can be deleted as a whole,
590       or correctly constructed.
591
592       . Example: of using resent groups
593
594        my $rgs = $msg->head->resentGroups;
595        $rgs[0]->delete if @rgs;
596
597        $msg->head->removeResentGroups;
598
599   The field's data
600       There are many ways to get the fields info as object, and there are
601       also many ways to process this data within the field.
602
603       Access to the field
604
605string()
606
607           Returns the text of the body exactly as will be printed to file
608           when print() is called, so name, main body, and attributes.
609
610foldedBody()
611
612           Returns the text of the body, like string(), but without the name
613           of the field.
614
615unfoldedBody()
616
617           Returns the text of the body, like foldedBody(), but then with all
618           new-lines removed.  This is the normal way to get the content of
619           unstructured fields.  Character-set encodings will still be in
620           place.  Fields are stringified into their unfolded representation.
621
622stripCFWS()
623
624           Returns the text of structured fields, where new-lines and comments
625           are removed from the string.  This is a good start for parsing the
626           field, for instance to find e-mail addresses in them.
627
628Mail::Message::Field::Full::decodedBody()
629
630           Studied fields can produce the unfolded text decoded into utf8
631           strings.  This is an expensive process, but the only correct way to
632           get the field's data.  More useful for people who are not living in
633           ASCII space.
634
635       •   Studied fields
636
637           Studied fields have powerful methods to provide ways to access and
638           produce the contents of (structured) fields exactly as the involved
639           rfcs prescribe.
640
641       Using simplified field access
642
643       Some fields are accessed that often that there are support methods to
644       provide simplified access.  All these methods are called upon a message
645       directly.
646
647       . Example: of simplified field access
648
649        print $message->subject;
650        print $message->get('subject') || '';  # same
651
652        my @from = $message->from; # returns addresses
653        $message->reply->send if $message->sender;
654
655       The "sender" method will return the address specified in the "Sender"
656       field, or the first named in the "From" field.  It will return "undef"
657       in case no address is known.
658
659       Specifying field data
660
661       Field data can be anything, strongly dependent on the type of field at
662       hand. If you decide to construct the fields very carefully via some
663       Mail::Message::Field::Full extension (like via
664       Mail::Message::Field::Addresses objects), then you will have protection
665       build-in.  However, you can bluntly create any Mail::Message::Field
666       object based on some data.
667
668       When you create a field, you may specify a string, object, or an array
669       of strings and objects.  On the moment, objects are only used to help
670       the construction on e-mail addresses, however you may add some of your
671       own.
672
673       The following rules (implemented in stringifyData()) are obeyed given
674       the argument is:
675
676       •   a string
677
678           The string must be following the (complicated) rules of the
679           rfc2822, and is made field content as specified.  When the string
680           is not terminated by a new-line ("\n") it will be folded according
681           to the standard rules.
682
683       •   a Mail::Address object
684
685           The most used Perl object to parse and produce address lines.  This
686           object does not understand character set encodings in phrases.
687
688       •   a Mail::Identity object
689
690           As part of the User::Identity distribution, this object has full
691           understanding of the meaning of one e-mail address, related to a
692           person.  All features defined by rfc2822 are implemented.
693
694       •   a User::Identity object
695
696           A person is specified, which may have more than one
697           Mail::Identity's defined.  Some methods, like
698           Mail::Message::reply() and Mail::Message::forward() try to select
699           the right e-mail address smart (see their method descriptions), but
700           in other cases the first e-mail address found is used.
701
702       •   a User::Identity::Collection::Emails object
703
704           All Mail::Identity objects in the collection will be included in
705           the field as a group carying the name of the collection.
706
707       •   any other object
708
709           For all other objects, the stringification overload is used to
710           produce the field content.
711
712       •   an ARRAY
713
714           You may also specify an array with a mixture of any of the above.
715           The elements will be joined as comma-separated list.  If you do not
716           want comma's inbetween, you will have to process the array
717           yourself.
718
719       . Example: specifying simple field data
720
721        my $f = Mail::Message::Field->new(Subject => 'hi!');
722        my $b = Mail::Message->build(Subject => 'monkey');
723
724       . Example: s specifying e-mail addresses for a field
725
726        use Mail::Address;
727        my $fish = Mail::Address->new('Mail::Box', 'fish@tux.aq');
728        print $fish->format;   # ==> Mail::Box <fish@tux.aq>
729        my $exa  = Mail::Address->new(undef, 'me@example.com');
730        print $exa->format;    # ==> me@example.com
731
732        my $b = $msg->build(To => "you@example.com");
733        my $b = $msg->build(To => $fish);
734        my $b = $msg->build(To => [ $fish, $exa ]);
735
736        my @all = ($fish, "you@example.com", $exa);
737        my $b = $msg->build(To => \@all);
738        my $b = $msg->build(To => [ "xyz", @all ]);
739
740       . Example: specifying identities for a field
741
742        use User::Identity;
743        my $patrik = User::Identity->new
744         ( name      => 'patrik'
745         , full_name => "Patrik Fältström"  # from rfc
746         , charset   => "ISO-8859-1"
747         );
748        $patrik->add
749         ( email    => "him@home.net"
750         );
751
752        my $b = $msg->build(To => $patrik);
753
754        $b->get('To')->print;
755          # ==> =?ISO-8859-1?Q?Patrik_F=E4ltstr=F6m?=
756          #     <him@home.net>
757
758   Field class implementation
759       For performance reasons only, there are three types of fields: the
760       fast, the flexible, and the full understander:
761
762       •   Mail::Message::Field::Fast
763
764           "Fast" objects are not derived from a "Mail::Reporter".  The
765           consideration is that fields are so often created, and such a small
766           objects at the same time, that setting-up a logging for each of the
767           objects is relatively expensive and not really useful.  The fast
768           field implementation uses an array to store the data: that will be
769           faster than using a hash.  Fast fields are not easily inheritable,
770           because the object creation and initiation is merged into one
771           method.
772
773       •   Mail::Message::Field::Flex
774
775           The flexible implementation uses a hash to store the data.  The
776           new() and "init" methods are split, so this object is extensible.
777
778       •   Mail::Message::Field::Full
779
780           With a full implementation of all applicable RFCs (about 5), the
781           best understanding of the fields is reached.  However, this comes
782           with a serious memory and performance penalty.  These objects are
783           created from fast or flex header fields when study() is called.
784

DIAGNOSTICS

786       Warning: Field content is not numerical: $content
787           The numeric value of a field is requested (for instance the "Lines"
788           or "Content-Length" fields should be numerical), however the data
789           contains weird characters.
790
791       Warning: Illegal character in field name $name
792           A new field is being created which does contain characters not
793           permitted by the RFCs.  Using this field in messages may break
794           other e-mail clients or transfer agents, and therefore mutulate or
795           extinguish your message.
796
797       Error: Package $package does not implement $method.
798           Fatal error: the specific package (or one of its superclasses) does
799           not implement this method where it should. This message means that
800           some other related classes do implement this method however the
801           class at hand does not.  Probably you should investigate this and
802           probably inform the author of the package.
803

SEE ALSO

805       This module is part of Mail-Message distribution version 3.012, built
806       on February 11, 2022. Website: http://perl.overmeer.net/CPAN/
807

LICENSE

809       Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
810       contributors see ChangeLog.
811
812       This program is free software; you can redistribute it and/or modify it
813       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
814
815
816
817perl v5.34.0                      2022-03-01           Mail::Message::Field(3)
Impressum