
=head1 NAME

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

=head1 CLASS 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 => 'me@example.com');
 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

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');

=head2 Header Fields

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.

A head line is composed of two parts separated by a color (C<:>).  Before
the colon is called the I<name> of the field, and the right part the
I<body>.  In some lines, the body contains a semicolon (C<;>) which
indicates the start of something refered to as I<comment>.  This comment
is often used to contain I<attributes>: key-value pairs of information,
which is of course much more important than simply accompanying text.

=head2 folding

Many implementations of mail transfer agents (MTAs) have problems with
lines longer than 998 characters.  Many implementations of mail user agents
(MUAs) can not handle lines longer than 78 characters well.  MTAs are
programs which implement the SMTP protocol, like the C<sendmail> command
or a web-browser which sends e-mail.  MUAs are programs which people use to
read their e-mail, like C<mutt>, C<elm>, C<pine>, or also a web-browser.

To avoid the problems with long lines, head lines are often folded into
lines of 78 characters maximum.  Longer lines are wrapped, in RFC-terms
I<folded>.  On some places in the body of a field, a line-feed is
inserted.  The remaining part of the body is on the next line, which
MUST be preceeded by at least one white-space (tab or blank)

Some fields are called C<structured>: their structure is well-defined by
the RFC.  In these fields, their is more flexibility where folding may
take place.  Other fields only permit folding on white-spaces.

=head2 consideration

Mail::Message::Field is the only object in the Mail::Box suite
which is not derived from a 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.

For the same reason, the are two types of fields: the flexible and
the fast:

=over 4

=item * Mail::Message::Field::Flex

The flexible implementation uses a has to store the data.  The new()
and C<init> are split, so this object is extensible.

=item * Mail::Message::Field::Fast

The fast implementation uses an array to store the same data.  That
will be faster.  Furthermore, it is less extensible because the object
creation and initiation is merged into one method.

=back

As user of the object, there is not visible difference.

=head1 METHODS

=head2 Initiation

=over 4

=item B<new> DATA

(Class method) 
See Mail::Message::Field::Fast::new(), Mail::Message::Field::Flex::new(),
and Mail::Message::Field::Full::new().
By default, a C<Fast> field is produced.

 OPTION               DEFAULT
 log                  'WARNINGS'
 trace                'WARNINGS'

=over 4

=item B<log> =E<gt> LEVEL

See Mail::Reporter::new(log)

=item B<trace> =E<gt> LEVEL

See Mail::Reporter::new(trace)

=back

=back

=head2 The Field

=over 4

=item B<clone> 

Create a copy of this field object.

=item B<isStructured> 

(object method or class method)

Examples:

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

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

=item B<length> 

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

=back

=head2 Access to the Field

=over 4

=item B<Name> 

Returns the name of this field in original casing.  See name() as well.

=item B<addresses> 

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

Examples:

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

=item 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.

Examples:

 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'); # sets field

=item B<body> 

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 aby case, the string is unfolded.  

Whether the field is structured is defined by isStructured().
This method may be what you want, but usually, the foldedBody() and
unfoldedBody() are what you are looking for.

=item 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 isStructured().

The I<comment> part of a header field often contains C<attributes>.  Often
it is preferred to use attributes() on them.

=item B<dateToTimestamp> STRING

(Class or Instance method) 
Convert a STRING which represents and RFC compliant time string into
a timestamp like is produced by the C<time> function.

=item 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 foldedBody() to get the same information without the field's name.

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

Examples:

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

=item 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 B<name> 

Returns the name of this field, with all characters lower-cased for
ease of comparison.  See Name() as well.

=item B<nrLines> 

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

=item B<print> [FILEHANDLE]

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 FILEHANDLE defaults to the selected handle.

=item B<size> 

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

=item B<string> [WRAP]

Returns the field as string.  By default, this returns the same as
folded(). However, the optional WRAP will cause to re-fold to take
place (without changing the folding stored inside the field).

=item B<stripCFWS> [STRING]

(Class or Instance method) 
Remove the I<comments> and I<folding white
spaces> from the STRING.  Without string and only as instance method, the
unfoldedBody() 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 B<toDate> [TIME]

(Class or Instance method) 
Convert a timestamp into a MIME-acceptable 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.  Be sure to have
your timezone set right, especially when this script runs automatically.

Examples:

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

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

=item 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 Mail::Message::printUndisclosed()

=item B<toInt> 

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

=item 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.

Examples:

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

=item 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.

Examples:

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

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

=back

=head2 Reading and Writing [internals]

=over 4

=item 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 new(), and usually not be an application
program.

=item 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 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 B<setWrapLength> [LENGTH]

Force the wrapping of this field to the specified LENGTH characters. The
wrapping is performed with fold() and the results stored within
the field object.

Without LENGTH, the message will be folded, unless it is already folded.
Pre-folded lines are detected on a trailing new-line character.

Examples:

 $field->setWrapLength(99);
 $field->setWrapLength;

=item B<unfold> STRING

The reverse of fold(): 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 Logging and Tracing

=over 4

=item B<defaultTrace> [LEVEL, [LEVEL]

See Mail::Reporter::defaultTrace()

=item B<errors> 

See Mail::Reporter::errors()

=item B<log> [LEVEL [,STRINGS]]

See Mail::Reporter::log()

=item B<report> [LEVEL]

See Mail::Reporter::report()

=item B<reportAll> [LEVEL]

See Mail::Reporter::reportAll()

=item B<trace> [LEVEL]

See Mail::Reporter::trace()

=item B<warnings> 

See Mail::Reporter::warnings()

=back

=head2 Other Methods

=over 4

=item B<AUTOLOAD> 

See Mail::Reporter::AUTOLOAD()

=item B<DESTROY> 

See Mail::Reporter::DESTROY()

=item B<inGlobalDestruction> 

See Mail::Reporter::inGlobalDestruction()

=item B<logPriority> LEVEL

See Mail::Reporter::logPriority()

=item B<logSettings> 

See Mail::Reporter::logSettings()

=item B<notImplemented> 

See Mail::Reporter::notImplemented()

=back

=head1 SEE ALSO

A good start to read is Mail::Box-Overview.
More documentation and a mailinglist are available from the project's
website at L<http://perl.overmeer.net/mailbox/>.

=head1 AUTHOR

Written by Mark Overmeer (L<mark@overmeer.net|mailto:mark@overmeer.net>)
with the help of many.  See the ChangeLog for details.

=head1 VERSION

This code is beta, version 2.037.

Copyright (c) 2001-2003 by the authors. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
