
=head1 NAME


Mail::Message::Head - the header of one message

=head1 CLASS INHERITANCE

Mail::Message::Head
   is a Mail::Reporter

Mail::Message::Head is extended by
   Mail::Message::Head::Complete
   Mail::Message::Head::Delayed
   Mail::Message::Head::Subset

=head1 SYNOPSIS


 my $head = Mail::Message::Head->new;
 $head->add('From: me@localhost');
 $head->add(From => 'me@localhost');
 $head->add(Mail::Message::Field->new(From => 'me'));
 my Mail::Message::Field $subject = $head->get('subject');
 my Mail::Message::Field @rec = $head->get('received');
 $head->delete('From');

=head1 DESCRIPTION


Mail::Message::Head MIME headers are part of Mail::Message messages,
which are stored by Mail::Box folders.

The header of a MIME message object contains a set of lines, which are
called I<fields> (by default represented by Mail::Message::Field
objects).  Dependent on the situation, the knowledge about the fields can
be in one of three situations, each represented by a sub-class of this
module:

=over 4

=item * Mail::Message::Head::Complete

In this case, it is sure that all knowledge about the header is available.
When you get() information from the header and it is not there, it will
never be there.

=item * Mail::Message::Head::Subset

There is no certainty whether all header lines are known (probably not).  This
may be caused as result of reading a fast index file, as described in
Mail::Box::MH::Index.  The object is automatically transformed
into a Mail::Message::Head::Complete when all header lines must be known.

=item * Mail::Message::Head::Delayed

In this case, there is no single field known.  Access to this header will
always trigger the loading of the full header.

=back

On this page, the general methods which are available on any header are
described.  Read about differences in the sub-class specific pages.

=head1 METHODS

=head2 Initiation

=over 4

=item B<build> FIELDS X<build>

A fast way to construct a header with many lines.  The FIELDS are
name--content pairs of the header.   A header is created, and each
pair is added.  Doubles are permitted.

Examples:

 my $head = Mail::Message::Head->build
  ( From     => 'me@example.com'
  , To       => 'you@anywhere.aq'
  , Received => 'one'
  , Received => 'two'
  );

=item B<new> OPTIONS X<new>

Create a new message header object.  The object will store all the
fields of a header.  When you get information from the header, it
will be returned to you as Mail::Message::Field objects, although
the fields may be stored differently internally.

If you try to instantiate a Mail::Message::Head, you will automatically
be upgraded to a Mail::Message::Head::Complete --a full head.

 OPTION               DEFAULT
 field_type           'Mail::Message::Field::Fast'
 log                  'WARNINGS'
 message              undef
 modified             <false>
 trace                'WARNINGS'
 wrap_length          72

=over 4

=item B<field_type> =E<gt> CLASS X<new(field_type)>

The type of objects that all the fields will have.  This must be
an extension of Mail::Message::Field.

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

See Mail::Reporter::new(log)

=item B<message> =E<gt> MESSAGE X<new(message)>

The MESSAGE where this header belongs to.  Usually, this is not known
at creation of the header, but sometimes it is.  If not, call the
message() method later to set it.

=item B<modified> =E<gt> BOOLEAN X<new(modified)>

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

See Mail::Reporter::new(trace)

=item B<wrap_length> =E<gt> INTEGER X<new(wrap_length)>

Set the desired maximum length of structured header fields to the
specified INTEGER.  If wrap_length is less than 1, wrapping is
disabled.

=back

=back

=head2 The Header

=over 4

=item B<isDelayed>  X<isDelayed>

Headers may only be partially read, in which case they are called delayed.
This method returns true if some header information still needs to be
read. Returns false if all header data has been read.
Will never trigger completion.

=item B<isEmpty>  X<isEmpty>

Are there any fields defined in the current header?  Be warned that
the header will not be loaded for this: delayed headers will return
true in any case.

=item B<isMultipart>  X<isMultipart>

Returns whether the body of the related message is a multipart body.
May trigger completion.

=item B<isResent>  X<isResent>

Return whether this message is the result of a bounce.  The bounce
will produced lines which start with C<Resent->, line C<Resent-To>
which has preference over C<To> as destination for the message.
This may trigger completion.

=item B<message> [MESSAGE] X<message>

Get (after setting) the message where this header belongs to.
This does not trigger completion.

=item B<modified> [BOOLEAN] X<modified>

Returns whether the header has been modified after being read, optionally
after setting that status first.
This will not trigger completion.

Examples:

 if($head->modified) { ... }
 $head->modified(1);

=back

=head2 Access to the Header

=over 4

=item B<get> NAME [,INDEX] X<get>

Get the data which is related to the field with the NAME.  The case of the
characters in NAME does not matter.

If there is only one data element defined for the NAME, or if there is an
INDEX specified as the second argument, only the specified element will be
returned. If the field NAME matches more than one header the return value
depends on the context. In LIST context, all values will be returned in
the order they are read. In SCALAR context, only the last value will be
returned.

Examples:

 my $head = Mail::Message::Head->new;
 $head->add('Received: abc');
 $head->add('Received: xyz');
 $head->add('Subject: greetings');

 my @rec_list   = $head->get('Received');
 my $rec_scalar = $head->get('Received');
 print ",@rec_list,$rec_scalar,"     # ,abc xyz, xyz,
 print $head->get('Received', 0);    # abc
 my @sub_list   = $head->get('Subject');
 my $sub_scalar = $head->get('Subject');
 print ",@sub_list,$sub_scalar,"     # ,greetings, greetings,

=item B<knownNames>  X<knownNames>

Like names(), but only returns the known header fields, which
may be less than names() for header types which are partial.
Will never trigger completion.

=item B<printUndisclosed> [FILEHANDLE] X<printUndisclosed>

Like the usual print(), the header lines are printed to the specified
FILEHANDLE, by default the selected filehandle.  In this case, however,
C<Bcc> and C<Resent-Bcc> lines are included.

=back

=head2 Reading and Writing [internals]

=over 4

=item B<addNoRealize> FIELD X<addNoRealize>

Add a field, like add() does, but avoid the loading of a possibly partial
header.  This method does not test the validity of the argument, nor flag
the header as changed.  This does not trigger completion.

=item B<fileLocation>  X<fileLocation>

Returns the location of the header in the file, as a pair begin and end.  The
begin is the first byte of the header.  The end is the first byte after
the header.

=item B<load>  X<load>

Be sure that the header is loaded.  This returns the loaded header
object.

=item B<moveLocation> DISTANCE X<moveLocation>

Move the registration of the header in the file.

=item B<read> PARSER X<read>

Read the header information of one message into this header structure.  This
method is called by the folder object (some Mail::Box sub-class), which
passes the PARSER as an argument.  Do not call this method yourself!

=item B<setNoRealize> FIELD X<setNoRealize>

Set a field, but avoid the loading of a possibly partial header as set()
does.  This method does not test the validity of the argument, nor flag the
header as changed.  This does not trigger completion.

=item B<wrapLength> [CHARS] X<wrapLength>

Returns the soft upper limit length of header lines, optionally after
setting it to CHARS first.

=back

=head2 Logging and Tracing

=over 4

=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

Mark Overmeer (L<mark@overmeer.net|mailto:mark@overmeer.net>) with the help of many.

=head1 VERSION

This code is beta, version 2.019.

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