/ 
Mail-Box-2.019
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Message::Head::Complete

NAME

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

CLASS INHERITANCE

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

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

SYNOPSIS

my $head = Mail::Message::Head::Complete->new;
See Mail::Message::Head

DESCRIPTION

A mail's message can be in various states: unread, partially read, and fully read. The class stores a message of which all header lines are known for sure.

METHODS

Initiation

build FIELDS

See Mail::Message::Head::build()

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

See Mail::Message::Head::new(field_type)

log => LEVEL

See Mail::Reporter::new(log)

message => MESSAGE

See Mail::Message::Head::new(message)

modified => BOOLEAN

See Mail::Message::Head::new(modified)

trace => LEVEL

See Mail::Reporter::new(trace)

wrap_length => INTEGER

See Mail::Message::Head::new(wrap_length)

The Header

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.

Examples:

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

See Mail::Message::Head::isDelayed()

isEmpty

See Mail::Message::Head::isEmpty()

isMultipart

See Mail::Message::Head::isMultipart()

isResent

See Mail::Message::Head::isResent()

message [MESSAGE]

See Mail::Message::Head::message()

modified [BOOLEAN]

See Mail::Message::Head::modified()

Constructing a Header

add FIELD | LINE | 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). Triggers Completion.

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

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;
set FIELD | LINE | 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.

Access to the Header

count NAME

Count the number of fields with this NAME. Most fields will return 1: only one occurance in the header. As example, the Received fields are usually present more than once.

get NAME [,INDEX]

See Mail::Message::Head::get()

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

Make a guess about when the message was origanally posted, based on the information found in the header.

For some kinds of folders, Mail::Box::guessTimestamp() may produce a better result, for instance by looking at the modification time of the file in which the message is stored. Also some protocols, like POP can supply that information.

knownNames

See Mail::Message::Head::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.

nrLines

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

Print all headers to the specified FILEHANDLE, by default the selected filehandle. See printUndisclosed() to limit the headers to include only the public headers.

Examples:

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

my $fh = FileHandle->new(...);
$head->print($fh);
printUndisclosed [FILEHANDLE]

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

size

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

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 usable for the gmtime and localtime methods.

toString

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

Reading and Writing [internals]

addNoRealize FIELD

See Mail::Message::Head::addNoRealize()

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.

fileLocation

See Mail::Message::Head::fileLocation()

load

See Mail::Message::Head::load()

moveLocation DISTANCE

See Mail::Message::Head::moveLocation()

read PARSER

See Mail::Message::Head::read()

setNoRealize FIELD

See Mail::Message::Head::setNoRealize()

wrapLength [CHARS]

See Mail::Message::Head::wrapLength()

Logging and Tracing

errors

See Mail::Reporter::errors()

log [LEVEL [,STRINGS]]

See Mail::Reporter::log()

report [LEVEL]

See Mail::Reporter::report()

reportAll [LEVEL]

See Mail::Reporter::reportAll()

trace [LEVEL]

See Mail::Reporter::trace()

warnings

See Mail::Reporter::warnings()

Other Methods

AUTOLOAD

See Mail::Reporter::AUTOLOAD()

DESTROY

See Mail::Reporter::DESTROY()

inGlobalDestruction

See Mail::Reporter::inGlobalDestruction()

logPriority LEVEL

See Mail::Reporter::logPriority()

logSettings

See Mail::Reporter::logSettings()

notImplemented

See Mail::Reporter::notImplemented()

SEE ALSO

A good start to read is Mail::Box-Overview. More documentation and a mailinglist are available from the project's website at http://perl.overmeer.net/mailbox/.

AUTHOR

Mark Overmeer (mark@overmeer.net) with the help of many.

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.