
=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

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 Performance consideration

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

On the other hand: full understanding of fields is really, really
expensive.  It should be used as rarely as possible to keep a little
performance in your program.

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

=over 4

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

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

=item * L<Mail::Message::Field::Fast|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.

=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 Mail::Message subroutine study or
Mail::Message::Head subroutine study are called.

=back

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


=head1 OVERLOADED


overload: B<"">

=over 4

(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()|"Access to the body">.

I<Example:> 

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

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

=back

overload: B<+0>

=over 4

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

=back

overload: B<<=>>

=over 4

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

I<Example:> 

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

=back

overload: B<bool>

=over 4

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

=back

overload: B<cmp>

=over 4

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

=back


=head1 METHODS


=head2 Constructors


$obj-E<gt>B<clone>

=over 4

Create a copy of this field object.

=back

Mail::Message::Field-E<gt>B<new>(DATA)

=over 4

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

 Option  Defined in       Default      
 log     L<Mail::Reporter>  C<'WARNINGS'>
 trace   L<Mail::Reporter>  C<'WARNINGS'>

. log LEVEL

. trace LEVEL

=back

=head2 The field


$obj-E<gt>B<isStructured>

Mail::Message::Field-E<gt>B<isStructured>

=over 4

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.

I<Example:> 

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

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

=back

$obj-E<gt>B<length>

=over 4

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

=back

$obj-E<gt>B<nrLines>

=over 4

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

=back

$obj-E<gt>B<print>([FILEHANDLE])

=over 4

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.

=back

$obj-E<gt>B<size>

=over 4

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

=back

$obj-E<gt>B<string>([WRAP])

=over 4

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

=back

$obj-E<gt>B<toDisclose>

=over 4

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()|"Access to the header">.

=back

=head2 Access to the name


$obj-E<gt>B<Name>

=over 4

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

=back

$obj-E<gt>B<name>

=over 4

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

=back

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

=over 4

(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.

I<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


$obj-E<gt>B<body>

=over 4

This method may be what you want, but usually, the L<foldedBody()|"Access to the body"> and
L<unfoldedBody()|"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 aby case, the string is unfolded.  
Whether the field is structured is defined by L<isStructured()|"The field">.

=back

$obj-E<gt>B<folded>

=over 4

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()|"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...

I<Example:> 

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

=back

$obj-E<gt>B<foldedBody>([BODY])

=over 4

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.

=back

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

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

=over 4

Remove the I<comments> and I<folding white
spaces> from the STRING.  Without string and only as instance method, the
L<unfoldedBody()|"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.

=back

$obj-E<gt>B<unfoldedBody>([BODY, [WRAP]])

=over 4

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.

I<Example:> 

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

=back

=head2 Access to the content


$obj-E<gt>B<addresses>

=over 4

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

I<Example:> 

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

=back

$obj-E<gt>B<attribute>(NAME [, VALUE])

=over 4

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.

I<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.

=back

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

=over 4

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()|"The field">.

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

=back

$obj-E<gt>B<toDate>([TIME])

Mail::Message::Field-E<gt>B<toDate>([TIME])

=over 4

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

I<Example:> 

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

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

=back

$obj-E<gt>B<toInt>

=over 4

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

=back

=head2 Other methods


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

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

=over 4

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

=back

=head2 Internals


$obj-E<gt>B<consume>(LINE | (NAME,BODY|OBJECTS))

=over 4

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()|"Constructors">, and usually not be an application
program.

=back

$obj-E<gt>B<defaultWrapLength>([LENGTH])

=over 4

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.

=back

$obj-E<gt>B<fold>(NAME, BODY, [MAXCHARS])

=over 4

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.

=back

$obj-E<gt>B<setWrapLength>([LENGTH])

=over 4

Force the wrapping of this field to the specified LENGTH characters. The
wrapping is performed with L<fold()|"Internals"> 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.

I<Example:> 

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

=back

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

=over 4

The reverse action of L<fold()|"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


$obj-E<gt>B<AUTOLOAD>

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<defaultTrace>([LEVEL, [LEVEL])

Mail::Message::Field-E<gt>B<defaultTrace>([LEVEL, [LEVEL])

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<errors>

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<log>([LEVEL [,STRINGS]])

Mail::Message::Field-E<gt>B<log>([LEVEL [,STRINGS]])

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<logPriority>(LEVEL)

Mail::Message::Field-E<gt>B<logPriority>(LEVEL)

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<logSettings>

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<notImplemented>

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<report>([LEVEL])

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<reportAll>([LEVEL])

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<trace>([LEVEL])

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<warnings>

=over 4

See L<Mail::Reporter/"Error handling">

=back

=head2 Cleanup


$obj-E<gt>B<DESTROY>

=over 4

See L<Mail::Reporter/"Cleanup">

=back

$obj-E<gt>B<inGlobalDestruction>

=over 4

See L<Mail::Reporter/"Cleanup">

=back



=head1 DIAGNOSTICS

I<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.

I<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.

I<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.






=head1 REFERENCES

See the Mail::Box website at L<http://perl.overmeer.net/mailbox/> for more details.

=head1 COPYRIGHTS

Module version 2.042.
Written by Mark Overmeer (mark@overmeer.net).  See the ChangeLog for
other contributors.

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


