NAME

Mail::Message::Head - the header of one Mail::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

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

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

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]

Prefixed methods are described in MR = Mail::Reporter.

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

Examples:

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

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

Print the header to the specified FILEHANDLE.

Example:

    $head->print(\*STDOUT);

    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 timestamp, with as little guessing as possible. This 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);

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]

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.

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

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

Copyright (c) 2001 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.