This file is indexed.

/usr/share/perl5/Mail/Message/Field.pod is in libmail-box-perl 2.118-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
=encoding utf8

=head1 NAME

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

=head1 INHERITANCE

 Mail::Message::Field
   is a Mail::Reporter

 Mail::Message::Field is extended by
   Mail::Message::Field::Fast
   Mail::Message::Field::Flex
   Mail::Message::Field::Full

=head1 SYNOPSIS

 my $field = Mail::Message::Field->new(From => 'fish@tux.aq');
 print $field->name;
 print $field->body;
 print $field->comment;
 print $field->content;  # body & comment
 $field->print(\*OUT);
 print $field->string;
 print "$field\n";
 print $field->attribute('charset') || 'us-ascii';

=head1 DESCRIPTION

This implementation follows the guidelines of rfc2822 as close as possible,
and may there produce a different output than implementations based on
the obsolete rfc822.  However, the old output will still be accepted.

These objects each store one header line, and facilitates access routines to
the information hidden in it.  Also, you may want to have a look at the
added methods of a message:

 my @from    = $message->from;
 my $sender  = $message->sender;
 my $subject = $message->subject;
 my $msgid   = $message->messageId;

 my @to      = $message->to;
 my @cc      = $message->cc;
 my @bcc     = $message->bcc;
 my @dest    = $message->destinations;

 my $other   = $message->get('Reply-To');

Extends L<"DESCRIPTION" in Mail::Reporter|Mail::Reporter/"DESCRIPTION">.
 
=head1 OVERLOADED

=over 4

=item overload: B<"">

(stringification) produces the unfolded body of the field, which may
be what you expect.  This is what makes what the field object seems
to be a simple string. The string is produced by L<unfoldedBody()|Mail::Message::Field/"Access to the body">.

example: 

 print $msg->get('subject');  # via overloading
 print $msg->get('subject')->unfoldedBody; # same

 my $subject = $msg->get('subject') || 'your mail';
 print "Re: $subject\n";

=item overload: B<0+>

(numification) When the field is numeric, the value will be returned.
The result is produced by L<toInt()|Mail::Message::Field/"Access to the content">.  If the value is not correct,
a C<0> is produced, to simplify calculations.

=item overload: B<<=>>

(numeric comparison) Compare the integer field contents with something
else.

example: 

 if($msg->get('Content-Length') > 10000) ...
 if($msg->size > 10000) ... ; # same, but better

=item overload: B<bool>

Always true, to make it possible to say C<if($field)>.

=item overload: B<cmp>

(string comparison) Compare the unfolded body of a field with an other
field or a string, using the buildin C<cmp>.

=back

=head1 METHODS

Extends L<"METHODS" in Mail::Reporter|Mail::Reporter/"METHODS">.
 
=head2 Constructors

Extends L<"Constructors" in Mail::Reporter|Mail::Reporter/"Constructors">.
 
=over 4

=item $obj-E<gt>B<clone>()

Create a copy of this field object.

=item Mail::Message::Field-E<gt>B<new>($data)

See L<Mail::Message::Field::Fast::new()|Mail::Message::Field::Fast/"METHODS">,
L<Mail::Message::Field::Flex::new()|Mail::Message::Field::Flex/"METHODS">,
and L<Mail::Message::Field::Full::new()|Mail::Message::Field::Full/"METHODS">.
By default, a C<Fast> field is produced.

 -Option--Defined in     --Default
  log     Mail::Reporter   'WARNINGS'
  trace   Mail::Reporter   'WARNINGS'

=over 2

=item log => LEVEL

=item trace => LEVEL

=back

=back

=head2 The field

=over 4

=item $obj-E<gt>B<isStructured>()

=item Mail::Message::Field-E<gt>B<isStructured>()

Some fields are described in the RFCs as being I<structured>: having a
well described syntax.  These fields have common ideas about comments
and the like, what they do not share with unstructured fields, like
the C<Subject> field.

example: 

 my $field = Mail::Message::Field->new(From => 'me');
 if($field->isStructured)

 Mail::Message::Field->isStructured('From');

=item $obj-E<gt>B<length>()

Returns the total length of the field in characters, which includes the
field's name, body and folding characters.

=item $obj-E<gt>B<nrLines>()

Returns the number of lines needed to display this header-line.

=item $obj-E<gt>B<print>( [$fh] )

Print the whole header-line to the specified file-handle. One line may
result in more than one printed line, because of the folding of long
lines.  The $fh defaults to the selected handle.

=item $obj-E<gt>B<size>()

Returns the number of bytes needed to display this header-line, Same
as L<length()|Mail::Message::Field/"The field">.

=item $obj-E<gt>B<string>( [$wrap] )

Returns the field as string.  By default, this returns the same as
L<folded()|Mail::Message::Field/"Access to the body">. However, the optional $wrap will cause to re-fold to take
place (without changing the folding stored inside the field).

=item $obj-E<gt>B<toDisclose>()

Returns whether this field can be disclosed to other people, for instance
when sending the message to an other party.  Returns a C<true> or C<false>
condition.
See also L<Mail::Message::Head::Complete::printUndisclosed()|Mail::Message::Head::Complete/"Access to the header">.

=back

=head2 Access to the name

=over 4

=item $obj-E<gt>B<Name>()

Returns the name of this field in original casing.  See L<name()|Mail::Message::Field/"Access to the name"> as well.

=item $obj-E<gt>B<name>()

Returns the name of this field, with all characters lower-cased for
ease of comparison.  See L<Name()|Mail::Message::Field/"Access to the name"> as well.

=item $obj-E<gt>B<wellformedName>( [STRING] )

(Instance method class method)
As instance method, the current field's name is correctly formatted
and returned.  When a STRING is used, that one is formatted.

example: 

 print Mail::Message::Field->Name('content-type')
   # -->  Content-Type

 my $field = $head->get('date');
 print $field->Name;
   # -->  Date

=back

=head2 Access to the body

=over 4

=item $obj-E<gt>B<body>()

This method may be what you want, but usually, the L<foldedBody()|Mail::Message::Field/"Access to the body"> and
L<unfoldedBody()|Mail::Message::Field/"Access to the body"> are what you are looking for.  This method is
cultural heritage, and should be avoided.

Returns the body of the field.  When this field is structured, it will
be B<stripped> from everything what is behind the first semi-color (C<;>).
In any case, the string is unfolded.  
Whether the field is structured is defined by L<isStructured()|Mail::Message::Field/"The field">.

=item $obj-E<gt>B<folded>()

Returns the folded version of the whole header.  When the header is
shorter than the wrap length, a list of one line is returned.  Otherwise
more lines will be returned, all but the first starting with at least
one blank.  See also L<foldedBody()|Mail::Message::Field/"Access to the body"> to get the same information without
the field's name.

In scalar context, the lines are delived into one string, which is
a little faster because that's the way they are stored internally...

example: 

 my @lines = $field->folded;
 print $field->folded;
 print scalar $field->folded; # faster

=item $obj-E<gt>B<foldedBody>( [$body] )

Returns the body as a set of lines. In scalar context, this will be one line
containing newlines.  Be warned about the newlines when you do
pattern-matching on the result of thie method.

The optional $body argument changes the field's body.  The folding of the
argument must be correct.

=item $obj-E<gt>B<stripCFWS>( [STRING] )

=item Mail::Message::Field-E<gt>B<stripCFWS>( [STRING] )

Remove the I<comments> and I<folding white spaces> from the STRING.  Without
string and only as instance method, the L<unfoldedBody()|Mail::Message::Field/"Access to the body"> is being stripped
and returned.

WARNING: This operation is only allowed for structured header fields (which
are defined by the various RFCs as being so.  You don't want parts within
braces which are in the Subject header line to be removed, to give an
example.

=item $obj-E<gt>B<unfoldedBody>( [$body, [$wrap]] )

Returns the body as one single line, where all folding information (if
available) is removed.  This line will also NOT end on a new-line.

The optional $body argument changes the field's body.  The right folding is
performed before assignment.  The $wrap may be specified to enforce a
folding size.

example: 

 my $body = $field->unfoldedBody;
 print "$field";   # via overloading

=back

=head2 Access to the content

=over 4

=item $obj-E<gt>B<addresses>()

Returns a list of L<Mail::Address|Mail::Address> objects, which represent the
e-mail addresses found in this header line.

example: 

 my @addr = $message->head->get('to')->addresses;
 my @addr = $message->to;

=item $obj-E<gt>B<attribute>( $name, [$value] )

Get the value of an attribute, optionally after setting it to a new value.
Attributes are part of some header lines, and hide themselves in the
comment field.  If the attribute does not exist, then C<undef> is
returned.  The attribute is still encoded.

example: 

 my $field = Mail::Message::Field->new(
  'Content-Type: text/plain; charset="us-ascii"');

 print $field->attribute('charset');
   # --> us-ascii

 print $field->attribute('bitmap') || 'no'
   # --> no

 $field->atrribute(filename => '/tmp/xyz');
 $field->print;
   # --> Content-Type: text/plain; charset="us-ascii";
   #       filename="/tmp/xyz"
   # Automatically folded, and no doubles created.

=item $obj-E<gt>B<attributes>()

Returns a list of key-value pairs, where the values are not yet decoded.

example: 

 my %attributes = $head->get('Content-Disposition')->attributes;

=item $obj-E<gt>B<comment>( [STRING] )

Returns the unfolded comment (part after a semi-colon) in a structureed
header-line. optionally after setting it to a new STRING first.
When C<undef> is specified as STRING, the comment is removed.
Whether the field is structured is defined by L<isStructured()|Mail::Message::Field/"The field">.

The I<comment> part of a header field often contains C<attributes>.  Often
it is preferred to use L<attribute()|Mail::Message::Field/"Access to the content"> on them.

=item $obj-E<gt>B<study>()

Study the header field in detail: turn on the full parsing and detailed
understanding of the content of the fields.  L<Mail::Message::Field::Fast|Mail::Message::Field::Fast>
and L<Mail::Message::Field::Fast|Mail::Message::Field::Fast> objects will be transformed into any
L<Mail::Message::Field::Full|Mail::Message::Field::Full> object.

example: 

 my $subject = $msg->head->get('subject')->study;
 my $subject = $msg->head->study('subject');  # same
 my $subject = $msg->study('subject');        # same

=item $obj-E<gt>B<toDate>( [$time] )

=item Mail::Message::Field-E<gt>B<toDate>( [$time] )

Convert a timestamp into an rfc2822 compliant date format.  This differs
from the default output of C<localtime> in scalar context.  Without
argument, the C<localtime> is used to get the current time. $time can
be specified as one numeric (like the result of C<time()>) and as list
(like produced by c<localtime()> in list context).

Be sure to have your timezone set right, especially when this script
runs automatically.

example: 

 my $now = time;
 Mail::Message::Field->toDate($now);
 Mail::Message::Field->toDate(time);

 Mail::Message::Field->toDate(localtime);
 Mail::Message::Field->toDate;      # same
 # returns someting like:
 #     Wed, 28 Aug 2002 10:40:25 +0200

=item $obj-E<gt>B<toInt>()

Returns the value which is related to this field as integer.  A check is
performed whether this is right.

=back

=head2 Other methods

=over 4

=item $obj-E<gt>B<dateToTimestamp>(STRING)

=item Mail::Message::Field-E<gt>B<dateToTimestamp>(STRING)

Convert a STRING which represents and RFC compliant time string into
a timestamp like is produced by the C<time> function.

=back

=head2 Internals

=over 4

=item $obj-E<gt>B<consume>( $line | <$name,<$body|$objects>> )

Accepts a whole field $line, or a pair with the field's $name and $body. In
the latter case, the $body data may be specified as array of $objects which
are stringified.  Returned is a nicely formatted pair of two strings: the
field's name and a folded body.

This method is called by L<new()|Mail::Message::Field/"Constructors">, and usually not by an application
program. The details about converting the $objects to a field content
are explained in L</Specifying field data>.

=item $obj-E<gt>B<defaultWrapLength>( [$length] )

Any field from any header for any message will have this default wrapping.
This is maintained in one global variable.  Without a specified $length,
the current value is returned.  The default is 78.

=item $obj-E<gt>B<fold>( $name, $body, [$maxchars] )

=item Mail::Message::Field-E<gt>B<fold>( $name, $body, [$maxchars] )

Make the header field with $name fold into multiple lines.
Wrapping is performed by inserting newlines before a blanks in the
$body, such that no line exceeds the $maxchars and each line is as long
as possible.

The RFC requests for folding on nice spots, but this request is
mainly ignored because it would make folding too slow.

=item $obj-E<gt>B<setWrapLength>( [$length] )

Force the wrapping of this field to the specified $length characters. The
wrapping is performed with L<fold()|Mail::Message::Field/"Internals"> and the results stored within
the field object.

example: refolding the field

 $field->setWrapLength(99);

=item $obj-E<gt>B<stringifyData>(STRING|ARRAY|$objects)

This method implements the translation of user supplied objects into
ascii fields.  The process is explained in L</Specifying field data>.

=item $obj-E<gt>B<unfold>(STRING)

The reverse action of L<fold()|Mail::Message::Field/"Internals">: all lines which form the body of a field
are joined into one by removing all line terminators (even the last).
Possible leading blanks on the first line are removed as well.

=back

=head2 Error handling

Extends L<"Error handling" in Mail::Reporter|Mail::Reporter/"Error handling">.
 
=over 4

=item $obj-E<gt>B<AUTOLOAD>()

Inherited, see L<Mail::Reporter/"Error handling">

=item $obj-E<gt>B<addReport>($object)

Inherited, see L<Mail::Reporter/"Error handling">

=item $obj-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )

=item Mail::Message::Field-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )

Inherited, see L<Mail::Reporter/"Error handling">

=item $obj-E<gt>B<errors>()

Inherited, see L<Mail::Reporter/"Error handling">

=item $obj-E<gt>B<log>( [$level, [$strings]] )

=item Mail::Message::Field-E<gt>B<log>( [$level, [$strings]] )

Inherited, see L<Mail::Reporter/"Error handling">

=item $obj-E<gt>B<logPriority>($level)

=item Mail::Message::Field-E<gt>B<logPriority>($level)

Inherited, see L<Mail::Reporter/"Error handling">

=item $obj-E<gt>B<logSettings>()

Inherited, see L<Mail::Reporter/"Error handling">

=item $obj-E<gt>B<notImplemented>()

Inherited, see L<Mail::Reporter/"Error handling">

=item $obj-E<gt>B<report>( [$level] )

Inherited, see L<Mail::Reporter/"Error handling">

=item $obj-E<gt>B<reportAll>( [$level] )

Inherited, see L<Mail::Reporter/"Error handling">

=item $obj-E<gt>B<trace>( [$level] )

Inherited, see L<Mail::Reporter/"Error handling">

=item $obj-E<gt>B<warnings>()

Inherited, see L<Mail::Reporter/"Error handling">

=back

=head2 Cleanup

Extends L<"Cleanup" in Mail::Reporter|Mail::Reporter/"Cleanup">.
 
=over 4

=item $obj-E<gt>B<DESTROY>()

Inherited, see L<Mail::Reporter/"Cleanup">

=back

=head1 DETAILS

=head2 Field syntax

Fields are stored in the header of a message, which are represented by
L<Mail::Message::Head|Mail::Message::Head> objects. A field is a combination of a I<name>,
I<body>, and I<attributes>.  Especially the term "body" is cause for
confusion: sometimes the attributes are considered to be part of the body.

The name of the field is followed by a colon ("C<:>", not preceded by
blanks, but followed by one blank).  Each attribute is preceded by
a separate semi-colon ("C<;>").  Names of fields are case-insensitive and
cannot contain blanks.

=head3 Folding fields

Fields which are long can be folded to span more than one line.  The real
limit for lines in messages is only at 998 characters, however such long
lines are not easy to read without support of an application.  Therefore
rfc2822 (which defines the message syntax) specifies explicitly that
field lines can be re-formatted into multiple sorter lines without change
of meaning, by adding new-line characters to any field before any blank or
tab.

Usually, the lines are reformatted to create lines which are 78 characters
maximum. Some applications try harder to fold on nice spots, like before
attributes.  Especially the C<Received> field is often manually folded into
some nice layout.  In most cases however, it is preferred to produce lines
which are as long as possible but max 78.

BE WARNED that all fields can be subjected to folding, and that you usually
want the unfolded value.

=head3 Structured fields

The rfc2822 describes a large number of header fields explicitly.  These
fields have a defined meaning.  For some of the fields, like the C<Subject>
field, the meaning is straight forward the contents itself.  These fields
are the I<Unstructured Fields>.

Other fields have a well defined internal syntax because their content is
needed by e-mail applications. For instance, the C<To> field contains
addresses which must be understood by all applications in the same way.
These are the I<Structured Fields>, see L<isStructured()|Mail::Message::Field/"The field">.

=head3 Comments in fields

Stuctured fields can contain comments, which are pieces of text enclosed in
parenthesis.  These comments can be placed close to anywhere in the line
and must be ignored be the application.  Not all applications are capable
of handling comments correctly in all circumstances.

=head2 Getting a field

As many programs as there are handling e-mail, as many variations on
accessing the header information are requested.  Be careful which way
you access the data: read the variations described here and decide
which solution suites your needs best.

=head3 Using get() field

The C<get()> interface is copied from other Perl modules which can
handle e-mail messages.  Many applications which simply replace
L<Mail::Internet|Mail::Internet> objects by L<Mail::Message|Mail::Message> objects will work
without modification.

There is more than one get method.  The exact results depend on which
get you use.  When L<Mail::Message::get()|Mail::Message/"The header"> is called, you will get the
unfolded, stripped from comments, stripped from attributes contents of
the field as B<string>.  Character-set encodings will still be in the
string.  If the same fieldname appears more than once in the header,
only the last value is returned.

When L<Mail::Message::Head::get()|Mail::Message::Head/"Access to the header"> is called in scalar context, the
last field with the specified name is returned as field B<object>.
This object strinigfies into the unfolded contents of the field, including
attributes and comments.  In list context, all appearances of the field
in the header are returned as objects.

BE WARNED that some lines seem unique, but are not according to the
official rfc.  For instance, C<To> fields can appear more than once.
If your program calls C<get('to')> in scalar context, some information
is lost.

=head3 Using study() field

As the name C<study> already implies, this way of accessing the fields is
much more thorough but also slower.  The C<study> of a field is like a
C<get>, but provides easy access to the content of the field and handles
character-set decoding correctly.

The L<Mail::Message::study()|Mail::Message/"The header"> method will only return the last field
with that name as object.  L<Mail::Message::Head::study()|Mail::Message::Head/"Access to the header"> and
L<Mail::Message::Field::study()|Mail::Message::Field/"Access to the content"> return all fields when used in list
context.

=head3 Using resent groups

Some fields belong together in a group of fields.  For instance, a set
of lines is used to define one step in the mail transport process.  Each
step adds a C<Received> line, and optionally some C<Resent-*> lines and
C<Return-Path>.  These groups of lines shall stay together and in order
when the message header is processed.

The C<Mail::Message::Head::ResentGroup> object simplifies the access to
these related fields.  These resent groups can be deleted as a whole,
or correctly constructed.

=head2 The field's data

There are many ways to get the fields info as object, and there are also
many ways to process this data within the field.

=head3 Access to the field

=over 4

=item * L<string()|Mail::Message::Field/"The field">

Returns the text of the body exactly as will be printed to file when
L<print()|Mail::Message::Field/"The field"> is called, so name, main body, and attributes.

=item * L<foldedBody()|Mail::Message::Field/"Access to the body">

Returns the text of the body, like L<string()|Mail::Message::Field/"The field">, but without the name of
the field.

=item * L<unfoldedBody()|Mail::Message::Field/"Access to the body">

Returns the text of the body, like L<foldedBody()|Mail::Message::Field/"Access to the body">, but then with all
new-lines removed.  This is the normal way to get the content of
unstructured fields.  Character-set encodings will still be in place.
Fields are stringified into their unfolded representation.

=item * L<stripCFWS()|Mail::Message::Field/"Access to the body">

Returns the text of structured fields, where new-lines and comments are
removed from the string.  This is a good start for parsing the field,
for instance to find e-mail addresses in them.

=item * L<Mail::Message::Field::Full::decodedBody()|Mail::Message::Field::Full/"Access to the body">

Studied fields can produce the unfolded text decoded into utf8 strings.
This is an expensive process, but the only correct way to get the field's
data.  More useful for people who are not living in ASCII space.

=item * Studied fields

Studied fields have powerful methods to provide ways to access and produce
the contents of (structured) fields exactly as the involved rfcs prescribe.

=back

=head3 Using simplified field access

Some fields are accessed that often that there are support methods to
provide simplified access.  All these methods are called upon a message
directly.

=head3 Specifying field data

Field data can be anything, strongly dependent on the type
of field at hand. If you decide to contruct the fields very
carefully via some L<Mail::Message::Field::Full|Mail::Message::Field::Full> extension (like via
L<Mail::Message::Field::Addresses|Mail::Message::Field::Addresses> objects), then you will have protection
build-in.  However, you can bluntly create any L<Mail::Message::Field|Mail::Message::Field>
object based on some data.

When you create a field, you may specify a string, object, or an array
of strings and objects.  On the moment, objects are only used to help
the construction on e-mail addresses, however you may add some of your
own.

The following rules (implemented in L<stringifyData()|Mail::Message::Field/"Internals">) are obeyed given
the argument is:

=over 4

=item * a string

The string must be following the (complicated) rules of the rfc2822, and
is made field content as specified.  When the string is not terminated
by a new-line (C<"\n">) it will be folded according to the standard rules.

=item * a L<Mail::Address|Mail::Address> object

The most used Perl object to parse and produce address lines.  This object
does not understand character set encodings in phrases.

=item * a L<Mail::Identity|Mail::Identity> object

As part of the L<User::Identity|User::Identity> distribution, this object has full
understanding of the meaning of one e-mail address, related to a person.
All features defined by rfc2822 are implemented.

=item * a L<User::Identity|User::Identity> object

A person is specified, which may have more than one L<Mail::Identity|Mail::Identity>'s
defined.  Some methods, like L<Mail::Message::reply()|Mail::Message::Construct::Reply/"Constructing a message"> and
L<Mail::Message::forward()|Mail::Message::Construct::Forward/"Constructing a message"> try to select the right e-mail address
smart (see their method descriptions), but in other cases the first
e-mail address found is used.

=item * a L<User::Identity::Collection::Emails|User::Identity::Collection::Emails> object

All L<Mail::Identity|Mail::Identity> objects in the collection will be included in
the field as a group carying the name of the collection.

=item * any other object

For all other objects, the stringification overload is used to produce
the field content.

=item * an ARRAY

You may also specify an array with a mixture of any of the above.  The
elements will be joined as comma-separated list.  If you do not want
comma's inbetween, you will have to process the array yourself.

=back

=head2 Field class implementation

For performance reasons only, there are three types of fields: the
fast, the flexible, and the full understander:

=over 4

=item * L<Mail::Message::Field::Fast|Mail::Message::Field::Fast>

C<Fast> objects are not derived from a C<Mail::Reporter>.  The consideration
is that fields are so often created, and such a small objects at the same
time, that setting-up a logging for each of the objects is relatively
expensive and not really useful.
The fast field implementation uses an array to store the data: that
will be faster than using a hash.  Fast fields are not easily inheritable,
because the object creation and initiation is merged into one method.

=item * L<Mail::Message::Field::Flex|Mail::Message::Field::Flex>

The flexible implementation uses a hash to store the data.  The L<new()|Mail::Message::Field/"Constructors">
and C<init> methods are split, so this object is extensible.

=item * L<Mail::Message::Field::Full|Mail::Message::Field::Full>

With a full implementation of all applicable RFCs (about 5), the best
understanding of the fields is reached.  However, this comes with
a serious memory and performance penalty.  These objects are created
from fast or flex header fields when L<study()|Mail::Message::Field/"Access to the content"> is called.

=back

=head1 DIAGNOSTICS

=over 4

=item Warning: Field content is not numerical: $content

The numeric value of a field is requested (for instance the C<Lines> or
C<Content-Length> fields should be numerical), however the data contains
weird characters.

=item Warning: Illegal character in field name $name

A new field is being created which does contain characters not permitted
by the RFCs.  Using this field in messages may break other e-mail clients
or transfer agents, and therefore mutulate or extinguish your message.

=item Error: Package $package does not implement $method.

Fatal error: the specific package (or one of its superclasses) does not
implement this method where it should. This message means that some other
related classes do implement this method however the class at hand does
not.  Probably you should investigate this and probably inform the author
of the package.

=back

=head1 SEE ALSO

This module is part of Mail-Box distribution version 2.118,
built on February 26, 2015. Website: F<http://perl.overmeer.net/mailbox/>

=head1 LICENSE

Copyrights 2001-2015 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>