Message::Head(3)

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

CLASS HIERARCHY
 Mail::Message::Head
 is a Mail::Reporter

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 processed by "Mail::Box" folders. See "Mail::Box-Overview" first.

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:

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

* "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::Index". The object is automatically transformed into a "Mail::Message::Head::Complete" when all header lines must be known.

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

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

METHOD INDEX
Methods prefixed with an abbreviation are described in Mail::Reporter (MR).

The general methods for "Mail::Message::Head" objects:

      add ...                              new OPTIONS
      build FIELDS                         nrLines
      count NAME                           print [FILEHANDLE]
      delete NAME                          printUndisclosed [FILEHANDLE]
   MR errors                            MR report [LEVEL]
      get NAME [,INDEX]                 MR reportAll [LEVEL]
      isDelayed                            reset NAME, FIELDS
      isMultipart                          set ...
      isResent                             size
      knownNames                           timestamp
   MR log [LEVEL [,STRINGS]]               toString
      modified [BOOL]                   MR trace [LEVEL]
      names                             MR warnings

The extra methods for extension writers:

   MR AUTOLOAD                          MR inGlobalDestruction
   MR DESTROY                              load
      addNoRealize FIELD                MR logPriority LEVEL
      clone [FIELDS]                    MR logSettings
      createFromLine                       message [MESSAGE]
      createMessageId                      moveLocation DISTANCE
      fileLocation                      MR notImplemented
      grepNames [NAMES|ARRAY-OF-N...       read PARSER
      guessBodySize                        setNoRealize FIELD
      guessTimestamp                       wrapLength [CHARS]

METHODS

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.

    The following options can be specified:

     OPTION       DEFINED BY                DEFAULT
     field_type   Mail::Message::Head       'Mail::Message::Field::Fast'
     log          Mail::Reporter            'WARNINGS'
     message      Mail::Message::Head       undef
     modified     Mail::Message::Head       0
     trace        Mail::Reporter            'WARNINGS'
     wrap_length  Mail::Message::Head       72

    * field_type => CLASS
        The type of objects that all the fields will have. This must be an extension of "Mail::Message::Field".

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

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

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

    Example:

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

add FIELD
add LINE
add NAME, BODY [,COMMENT]
    Add a field to the header. If a field is added more than once, all values are stored in the header, in the order they are added.

    The return value of this method is the "Mail::Message::Field" object which is created (or was specified).

    Examples:

       my $head  = Mail::Message::Head->new;
       $head->add('Subject: hi!');
       $head->add(From => 'me@home');
       my $field = Mail::Message::Field->new('To: you@there');
       $head->add($field);
       my Mail::Message::Field $s = $head->add(Sender => 'I');

set FIELD
set LINE
set NAME, BODY [,COMMENT]
    The "set" method is similar to the "add()" method, and takes the same options. However, existing values for fields will be removed before a new value is added.

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,

count NAME
    Count the number of fields for this NAME.

reset NAME, FIELDS
    Replace the values in the header fields named by NAME with the values specified in the list of FIELDS. A single name can correspond to multiple repeated fields.

    If FIELDS is empty, the corresponding NAME fields will be removed. The location of removed fields in the header order will be remembered. Fields with the same name which are added later will appear at the remembered position. This is equivalent to the "delete" method.

    Examples:

        # reduce number of 'Received' lines to last 5)
        my @received = $head->get('Received');
        $head->reset('Received', @received[-5..-1]) if @received > 5;

delete NAME
    Remove the field with the specified name. If the header contained multiple lines with the same name, they will be replaced all together. This method simply calls "reset".

knownNames
names
    Returns a full ordered list of known field names, as defined in the header. Fields which were "reset()" to be empty will still be listed here. "knownNames" only returns the known header fields, which may be less than "names" for header types which are partial.

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.

isMultipart
print [FILEHANDLE]
printUndisclosed [FILEHANDLE]
    Print the header to the specified FILEHANDLE, by default the selected filehandle. In the former case, "Bcc" and "Resent-Bcc" lines are included, in the latter case not.

    Examples:

        $head->print(\*OUT);
        $head->print;

        my $fh = FileHandle->new(...);
        $head->print($fh);

toString
    Returns the whole header as one scalar (in scalar context) or list of lines (list context).

timestamp
    Will return a good indication of about when the message was send, with as little guessing as possible. The timestamp is encoded as "time" is on your system (see perldoc -f time), and as such useable for the "gmtime" and "localtime" methods. This method will trigger reading of the header (if not already read).

nrLines
    Return the number of lines needed to display this header (including the trailing newline)

size
    Return the number of bytes needed to display this header (including the trailing newline)

modified [BOOL]
    Returns whether the header has been modified after being read, optionally after setting that status first.

    Examples:

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

isResent
    Return whether this message is the result of a bounce. The bounce will produced lines which start with "Resent-", line "Resent-To" which has preference over "To" as destination for the message.

METHODS for extension writers

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. Do not call this method yourself!

clone [FIELDS]
    Make a copy of the header, optionally limited only to the header lines specified by FIELDS. The lines which are taken must start with one of the list. If no list is specified, all will be taken.

    Example:

       my $newhead = $head->clone('Subject', 'Received');

grepNames [NAMES|ARRAY-OF-NAMES|REGEXS]
    Filter from all header names the names which start will any of the specified list. When no names are specified, all names will be returned. The list is ordered as they where read from file, or added later.

    The NAMES are regular expressions, and will all be matched case insensitive and attached to the front of the string only. You may also specify one or more prepared regexes.

    Examples:

       print $head->grepNames();         # same as $head->names
       print $head->grepNames('X-', 'Subject', ');
       print $head->grepNames('To\b');   # will only select To

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.

guessTimestamp
    Try to get a good guess about the time this message was transmitted. This moment may be somewhere from start of transmission by the sender till receipt. It may return "undef".

message [MESSAGE]
    Get (after setting) the message where this header belongs to.

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

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.

moveLocation DISTANCE
    Move the registration of the header in the file.

createFromLine
    For some mail-folder types separate messages by a line starting with '"From "'. If a message is moved to such folder from a folder-type which does not support these separators, this method is called to produce one.

createMessageId
    Creates a message-id for this message. This method will be run when a new message is created, or a message is discovered without the message-id header field. Message-ids are required for detection of message-threads.

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

setNoRealize FIELD
    Set a field, 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.

addNoRealize FIELD
    Add a field, 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.

SEE ALSO
Mail::Box-Overview

For support and additional documentation, see http://perl.overmeer.net/mailbox/

AUTHOR
Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION
This code is beta, version 2.018.

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.