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


NAME

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


INHERITANCE

 Mail::Message::Head
   is a Mail::Reporter
 Mail::Message::Head is extended by
   Mail::Box::IMAP4::Head
   Mail::Message::Head::Complete
   Mail::Message::Head::Delayed
   Mail::Message::Head::Subset


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


DESCRIPTION

Mail::Message::Head MIME headers are part of Mail::Message messages, which are grouped in Mail::Box folders.

ATTENTION!!! most functionality about e-mail headers is described in Mail::Message::Head::Complete, which is a matured header object. Other kinds of headers will be translated to that type when time comes.

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


OVERLOADED

overload: ``''

(stringifaction) The header, when used as string, will format as if Mail::Message::Head::Complete::string() was called, so return a nicely folder full header. An exception is made for Carp, which will get a simplified string to avoid unreadible messages from croak and confess.

Example: using a header object as string

 print $head;     # implicit stringification by print
 $head->print;    # the same
 print "$head";   # explicit stringication

overload: bool

When the header does not contain any lines (which is illegal, according to the RFCs), false is returned. In all other cases, a true value is produced.


METHODS

Constructors

$obj->build([PAIR|FIELD]-LIST)

A fast way to construct a header with many lines. The PAIRs are (name, content) pairs of the header, but it is also possible to pass Mail::Message::Field objects. A Mail::Message::Head::Complete header is created by simply calling Mail::Message::Head::Complete::build(), and then each field is added. Double field names are permitted.

Example:

 my $subject = Mail::Message::Full->new(Subject => 'xyz');
 my $head = Mail::Message::Head->build
  ( From     => 'me@example.com'
  , To       => 'you@anywhere.aq'
  , $subject
  , Received => 'one'
  , Received => 'two'
  );
 print ref $head;
  # -->  Mail::Message::Head::Complete

Mail::Message::Head->new(OPTIONS)

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      Defined in       Default                                                 
 field_type                   L<Mail::Message::Field::Fast|Mail::Message::Field::Fast>
 log         L<Mail::Reporter>  C<'WARNINGS'>                                           
 message                      undef                                                   
 modified                     <false>                                                 
 trace       L<Mail::Reporter>  C<'WARNINGS'>

. field_type CLASS

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

. log LEVEL

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

. modified BOOLEAN

. trace LEVEL

The header

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

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

$obj->isModified

Returns whether the header has been modified after being read.

Example:

 if($head->isModified) { ... }

$obj->knownNames

Like Mail::Message::Head::Complete::names(), but only returns the known header fields, which may be less than names for header types which are partial. names() will trigger completion, where knownNames() does not.

$obj->message([MESSAGE])

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

$obj->modified([BOOLEAN])

Sets the modified flag to BOOLEAN. Without value, the current setting is returned, but in that case you can better use isModified(). Changing this flag will not trigger header completion.

Example:

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

$obj->orderedFields

Retuns the fields ordered the way they were read or added.

Access to the header

$obj->get(NAME [,INDEX])

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.

Example:

 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,

$obj->study(NAME [,INDEX])

Like get(), but puts more effort in understanding the contents of the field. Mail::Message::Field::study() will be called for the field with the specified FIELDNAME, which returns Mail::Message::Field::Full objects. In scalar context only the last field with that name is returned. When an INDEX is specified, that element is returned.

About the body

$obj->guessBodySize

Try to estimate the size of the body of this message, but without parsing the header or body. The result might be undef or a few percent of the real size. It may even be very far of the real value, that's why this is a guess.

$obj->isMultipart

Returns whether the body of the related message is a multipart body. May trigger completion, when the Content-Type field is not defined.

Internals

$obj->addNoRealize(FIELD)

Add a field, like Mail::Message::Head::Complete::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.

$obj->addOrderedFields(FIELDS)

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

$obj->load

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

$obj->moveLocation(DISTANCE)

Move the registration of the header in the file.

$obj->read(PARSER)

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.

$obj->setNoRealize(FIELD)

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.

Error handling

$obj->AUTOLOAD

See Error handling in the Mail::Reporter manpage

$obj->addReport(OBJECT)

See Error handling in the Mail::Reporter manpage

$obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

Mail::Message::Head->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

See Error handling in the Mail::Reporter manpage

$obj->errors

See Error handling in the Mail::Reporter manpage

$obj->log([LEVEL [,STRINGS]])

Mail::Message::Head->log([LEVEL [,STRINGS]])

See Error handling in the Mail::Reporter manpage

$obj->logPriority(LEVEL)

Mail::Message::Head->logPriority(LEVEL)

See Error handling in the Mail::Reporter manpage

$obj->logSettings

See Error handling in the Mail::Reporter manpage

$obj->notImplemented

See Error handling in the Mail::Reporter manpage

$obj->report([LEVEL])

See Error handling in the Mail::Reporter manpage

$obj->reportAll([LEVEL])

See Error handling in the Mail::Reporter manpage

$obj->trace([LEVEL])

See Error handling in the Mail::Reporter manpage

$obj->warnings

See Error handling in the Mail::Reporter manpage

Cleanup

$obj->DESTROY

See Cleanup in the Mail::Reporter manpage

$obj->inGlobalDestruction

See Cleanup in the Mail::Reporter manpage


DIAGNOSTICS

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.


DETAILS

Ordered header fields

Many Perl implementations make a big mistake by disturbing the order of header fields. For some fields (especially the resent groups, see Mail::Message::Head::ResentGroup) the order shall be maintained.

MailBox will keep the order of the fields as they were found in the source. When your add a new field, it will be added at the end. If your replace a field with a new value, it will stay in the original order.

Head class implementation

The header of a MIME message object contains a set of lines, which are called 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:

Subsets of header fields

Message headers can be quite large, and therefore MailBox provides simplified access to some subsets of information. You can grab these sets of fields together, create and delete them as group.

On the moment, the following sets are defined:


REFERENCES

See the MailBox website at http://perl.overmeer.net/mailbox/ for more details.


COPYRIGHTS

Distribution version 2.059. 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.

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