Mail::Message::Head::Complete - the header of one message |
Mail::Message::Head::Complete - the header of one message
Mail::Message::Head::Complete is a Mail::Message::Head is a Mail::Reporter
Mail::Message::Head::Complete is extended by Mail::Message::Head::Partial Mail::Message::Replace::MailHeader
Mail::Message::Head::Complete is realized by Mail::Message::Head::Delayed Mail::Message::Head::Subset
my $head = Mail::Message::Head::Complete->new; See Mail::Message::Head
E-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.
overload: ``''
See OVERLOADED in the Mail::Message::Head manpage
overload: bool
See OVERLOADED in the Mail::Message::Head manpage
$obj->build([PAIR|FIELD]-LIST)
$obj->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');
Mail::Message::Head::Complete->new(OPTIONS)
See Constructors in the Mail::Message::Head manpage
$obj->isDelayed
See The header in the Mail::Message::Head manpage
$obj->isEmpty
See The header in the Mail::Message::Head manpage
$obj->isModified
See The header in the Mail::Message::Head manpage
$obj->knownNames
See The header in the Mail::Message::Head manpage
$obj->message([MESSAGE])
See The header in the Mail::Message::Head manpage
$obj->modified([BOOLEAN])
See The header in the Mail::Message::Head manpage
$obj->nrLines
Return the number of lines needed to display this header (including the trailing newline)
$obj->orderedFields
See The header in the Mail::Message::Head manpage
$obj->size
Return the number of bytes needed to display this header (including the trailing newline). On systems which use CRLF as line separator, the number of lines in the header (see nrLines()) must be added to find the actual size in the file.
$obj->wrap(INTEGER)
Re-fold all fields from the header to contain at most INTEGER number of characters per line.
Example: re-folding a header
$msg->head->wrap(78);
$obj->add(FIELD | LINE | (NAME,BODY[,ATTRS]))
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.
When a FIELD object is specified (some Mail::Message::Field instance), that will be added. Another possibility is to specify a raw header LINE, or a header line nicely split-up in NAME and BODY, in which case the field constructor is called for you.
LINE or BODY specifications which are terminated by a new-line are considered to be correctly folded. Lines which are not terminated by a new-line will be folded when needed: new-lines will be added where required. It is strongly adviced to let MailBox do the folding for you.
The return value of this method is the Mail::Message::Field object which is created (or was specified).
Example:
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');
$obj->addListGroup(OBJECT)
A list group is a set of header fields which contain data about a mailing list which was used to transmit the message. See Mail::Message::Head::ListGroup for details about the implementation of the OBJECT.
When you have a list group prepared, you can add it later using this method. You will get your private copy of the list group data in return, because the same group can be used for multiple messages.
Example: of adding a list group to a header
my $lg = Mail::Message::Head::ListGroup->new(...); my $own_lg = $msg->head->addListGroup($lg);
$obj->addResentGroup(RESENT-GROUP|DATA)
Add a RESENT-GROUP (a Mail::Message::Head::ResentGroup object) to
the header. If you specify DATA, that is used to create such group
first. If no Received
line is specified, it will be created
for you.
These header lines have nothing to do with the user's sense
of reply
or forward
actions: these lines trace the e-mail
transport mechanism.
Example:
my $rg = Mail::Message::Head::ResentGroup->new(head => $head, ...); $head->addResentGroup($rg);
my $rg = $head->addResentGroup(From => 'me');
$obj->addSpamGroup(OBJECT)
A spam fighting group is a set of header fields which contains data which is used to fight spam. See Mail::Message::Head::SpamGroup for details about the implementation of the OBJECT.
When you have a spam group prepared, you can add it later using this method. You will get your private copy of the spam group data in return, because the same group can be used for multiple messages.
Example: of adding a spam group to a header
my $sg = Mail::Message::Head::SpamGroup->new(...); my $own_sg = $msg->head->addSpamGroup($sg);
$obj->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.
$obj->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() without replacement fields. READ THE IMPORTANT WARNING IN removeField()
$obj->get(NAME [,INDEX])
See Access to the header in the Mail::Message::Head manpage
$obj->grepNames([NAMES|ARRAY-OF-NAMES|REGEXS])
Filter from all header fields 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.
Example:
print $head->grepNames(); # same as $head->names print $head->grepNames('X-', 'Subject', '); print $head->grepNames('To\b'); # will only select To
$obj->listGroup
Returns a list group description: the set of headers which form the information about mailing list software used to transport the message. See also addListGroup() and removeListGroup().
Example: use of listGroup()
if(my $lg = $msg->head->listGroup) { $lg->print(\*STDERR); $lg->delete; }
$msg->head->removeListGroup;
$obj->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.
$obj->print([FILEHANDLE])
Print all headers to the specified FILEHANDLE, by default the selected filehandle. See printUndisclosed() to limit the headers to include only the public headers.
Example:
$head->print(\*OUT); $head->print;
my $fh = IO::File->new(...); $head->print($fh);
$obj->printSelected(FILEHANDLE, (STRING|REGEXP)s)
Like the usual print(), the header lines are printed to the specified FILEHANDLE. In this case, however, only the fields with names as specified by STRING (case insensative) or REGEXP are printed. They will stay the in-order of the source header.
Example: printing only a subset of the fields
$head->printSelected(STDOUT, qw/Subject From To/, qr/^x\-(spam|xyz)\-/i)
$obj->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.
$obj->removeContentInfo
Remove all body related fields from the header. The header will become partial.
$obj->removeField(FIELD)
Remove the specified FIELD object from the header. This is useful when there are possible more than one fields with the same name, and you need to remove exactly one of them. Also have a look at delete(), reset(), and set().
See also Mail::Message::Head::Partial::removeFields() (mind the 's' at the end of the name), which accepts a string or regular expression as argument to select the fields to be removed.
WARNING WARNING WARNING: for performance reasons, the header administration uses weak references (see the Scalar::Util manpage method weaken()> to figure-out which fields have been removed. A header is a hash of field for fast search and an array of weak references to remember the order of the fields, required for printing. If the field is removed from the hash, the weak-ref is set to undef and the field not printed.
However... it is easy to disturb this process. Example: my $msg = ....; # subject ref-count = 1 + 0 = 1 $msg->head->delete('Subject'); # subject ref-count = 0 = 0: clean-up $msg->print; # subject doesn't show: ok
But my $msg = ....; # subject ref-count = 1 + 0 = 1 my $s = $msg->head->get('subject'); # ref-count = 1 + 1 + 0 = 2 $msg->head->delete('Subject'); # subject ref-count = 1 + 0 = 1: no clean-up $msg->print; # subject DOES show: not ok undef $s; # ref-count becomes 0: clean-up $msg->print; # subject doesn't show: ok
To avoid the latter situation, do not catch the field object, but only the field content. SAVE are all methods which return the text: my $s = $msg->head->get('subject')->body; my $s = $msg->head->get('subject')->unfoldedBody; my $s = $msg->head->get('subject')->foldedBody; my $s = $msg->head->get('subject')->foldedBody; my $s = $msg->get('subject'); my $s = $msg->subject; my $s = $msg->string;
$obj->removeFields(STRING|REGEXP, [STRING|REGEXP, ...])
The header object is turned into a Mail::Message::Head::Partial object which has a set of fields removed. Read about the implications and the possibilities in Mail::Message::Head::Partial::removeFields().
$obj->removeFieldsExcept(STRING|REGEXP, [STRING|REGEXP, ...])
The header object is turned into a Mail::Message::Head::Partial object which has a set of fields removed. Read about the implications and the possibilities in Mail::Message::Head::Partial::removeFieldsExcept().
$obj->removeListGroup
Removes all fields related to mailing list administration at once. The header object is turned into a Mail::Message::Head::Partial object. Read about the implications and the possibilities in Mail::Message::Head::Partial::removeListGroup().
$obj->removeResentGroups
Removes all resent groups at once. The header object is turned into a Mail::Message::Head::Partial object. Read about the implications and the possibilities in Mail::Message::Head::Partial::removeResentGroups().
$obj->removeSpamGroups
Removes all fields which were added by various spam detection software at once. The header object is turned into a Mail::Message::Head::Partial object. Read about the implications and the possibilities in Mail::Message::Head::Partial::removeSpamGroups().
$obj->resentGroups
Returns a list of Mail::Message::Head::ResentGroup objects which each represent one intermediate point in the message's transmission in the order as they appear in the header: the most recent one first. See also addResentGroup() and removeResentGroups().
A resent group contains a set of header fields whose names start
with Resent-
. Before the first Resent
line is trace information,
which is composed of an optional Return-Path
field and an required
Received
field.
$obj->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. READ THE IMPORTANT WARNING IN removeField()
Removing fields which are part of one of the predefined field groups is
not a smart idea. You can better remove these fields as group, all
together. For instance, the 'Received'
lines are part of resent
groups, 'X-Spam'
is past of a spam group, and List-Post
belongs
to a list group. You can delete a whole group with
Mail::Message::Head::FieldGroup::delete(), or with methods which
are provided by Mail::Message::Head::Partial.
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.
Example:
# reduce number of 'Keywords' lines to last 5) my @keywords = $head->get('Keywords'); $head->reset('Keywords', @keywords[-5..-1]) if @keywords > 5;
# Reduce the number of Received lines to only the last added one. my @rgs = $head->resentGroups; shift @rgs; # keep this one (later is added in front) $_->delete foreach @rgs;
$obj->set(FIELD | LINE | (NAME, BODY [,ATTRS]))
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. READ THE IMPORTANT WARNING IN removeField()
$obj->spamDetected
Returns whether one of the spam groups defines a report about spam. If there
are not header fields in the message which relate to spam-detection
software, undef
is returned. The spamgroups which report spam are returned.
Example:
$message->delete if $message->spamDetected;
call_spamassassin($message) unless defined $message->spamDetected;
$obj->spamGroups([NAMES])
Returns a list of Mail::Message::Head::SpamGroup objects, each collecting some lines which contain spam fighting information. When any NAMES are given, then only these groups are returned. See also addSpamGroup() and removeSpamGroups().
In scalar context, with exactly one NAME specified, that group will be returned. With more NAMES or without NAMES, a list will be returned (which defaults to the length of the list in scalar context).
Example: use of listGroup()
my @sg = $msg->head->spamGroups; $sg[0]->print(\*STDERR); $sg[-1]->delete;
my $sg = $msg->head->spamGroups('SpamAssassin');
$obj->string
Returns the whole header as one scalar (in scalar context) or list of lines (list context). Triggers completion.
$obj->study(NAME [,INDEX])
See Access to the header in the Mail::Message::Head manpage
$obj->guessBodySize
See About the body in the Mail::Message::Head manpage
$obj->guessTimeStamp
Make a guess about when the message was origanally posted, based on the
information found in the header's Date
field.
For some kinds of folders, Mail::Message::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.
$obj->isMultipart
See About the body in the Mail::Message::Head manpage
$obj->recvstamp
Returns an indication about when the message was sent, but only using the
Date
field in the header as last resort: we do not trust the sender of
the message to specify the correct date. See timestamp() when you do
trust the sender.
Many spam producers fake a date, which mess up the order of receiving
things. The timestamp which is produced is derived from the Received
headers, if they are present, and undef
otherwise.
The timestamp is encoded as time
is on your system (see perldoc -f
time), and as such usable for the gmtime
and localtime
methods.
Example: of time-sorting folders with received messages
my $folder = $mgr->open('InBox'); my @messages = sort {$a->recvstamp <=> $b->recvstamp} $folder->messages;
Example: of time-sorting messages of mixed origin
my $folder = $mgr->open('MyFolder');
# Pre-calculate timestamps to be sorted (for speed) my @stamps = map { [ ($_->timestamp || 0), $_ ] } $folder->messages;
my @sorted = map { $_->[1] } # get the message for the stamp sort {$a->[0] <=> $b->[0]} # stamps are numerics @stamps;
$obj->timestamp
Returns an indication about when the message was sent, with as little guessing as possible. In this case, the date as specified by the sender is trusted. See recvstamp() when you do not want to trust the sender.
The timestamp is encoded as time
is
on your system (see perldoc -f time), and as such usable for the gmtime
and localtime
methods.
$obj->addNoRealize(FIELD)
See Internals in the Mail::Message::Head manpage
$obj->addOrderedFields(FIELDS)
See Internals in the Mail::Message::Head manpage
$obj->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.
$obj->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. See messageIdPrefix().
$obj->fileLocation
See Internals in the Mail::Message::Head manpage
$obj->load
See Internals in the Mail::Message::Head manpage
$obj->messageIdPrefix([PREFIX, [HOSTNAME]|CODE])
Mail::Message::Head::Complete->messageIdPrefix([PREFIX, [HOSTNAME]|CODE])
When options are provided, it sets a new way to create message-ids, as used by createMessageId(). You have two choices: either by providing a PREFIX and optionally a HOSTNAME, or a CODE reference.
The CODE reference will be called with the header as first argument. You must ensure yourself that the returned value is RFC compliant.
The PREFIX defaults to mailbox-$$
, the HOSTNAME defaults to the
return of the Sys::Hostname manpage's method hostname()
. Inbetween the
two, a nano-second time provided by the Time::Hires manpage is used. If that
module is not available, time
is called at the start of the program,
and incremented for each newly created id.
In any case, a subroutine will be created to be used. A reference to that will be returned. When the method is called without arguments, but no subroutine is defined yet, one will be created.
Example: setting a message prefix
$head->messageIdPrefix('prefix'); Mail::Message::Head::Complete->messageIdPrefix('prefix'); my $code = $head->messageIdPrefix('mailbox', 'nohost');
sub new_msgid() { my $head = shift; "myid-$$-${(rand 10000)}@example.com"; }
$many_msg->messageIdPrefix(\&new_msgid); Mail::Message::Head::Complete->messageIdPrefix(&new_msgid);
$obj->moveLocation(DISTANCE)
See Internals in the Mail::Message::Head manpage
$obj->read(PARSER)
See Internals in the Mail::Message::Head manpage
$obj->setNoRealize(FIELD)
See Internals in the Mail::Message::Head manpage
$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::Complete->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::Complete->log([LEVEL [,STRINGS]])
See Error handling in the Mail::Reporter manpage
$obj->logPriority(LEVEL)
Mail::Message::Head::Complete->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
$obj->DESTROY
See Cleanup in the Mail::Reporter manpage
$obj->inGlobalDestruction
See Cleanup in the Mail::Reporter manpage
Warning: Cannot remove field $name from header: not found.
You ask to remove a field which is not known in the header. Using delete(), reset(), or set() to do the job will not result in warnings: those methods check the existence of the field first.
Warning: Field objects have an implied name ($name)
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.
See the MailBox website at http://perl.overmeer.net/mailbox/ for more details.
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::Complete - the header of one message |