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::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 Mail::Message::Head
overload: bool
$obj->build(FIELDS)
See "Constructors" in Mail::Message::Head
$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)
$obj->isDelayed
See "The header" in Mail::Message::Head
$obj->isEmpty
$obj->isModified
$obj->knownNames
$obj->message([MESSAGE])
$obj->modified([BOOLEAN])
$obj->nrLines
Return the number of lines needed to display this header (including the trailing newline)
$obj->orderedFields
$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->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 Mail::Box do the folding for you.
The return value of this method is the Mail::Message::Field object which is created (or was specified).
my $head = L<Mail::Message::Head|Mail::Message::Head>->new; $head->add('Subject: hi!'); $head->add(From => 'me@home'); my $field = L<Mail::Message::Field|Mail::Message::Field>->new('To: you@there'); $head->add($field); my Mail::Message::Field $s = $head->add(Sender => 'I');
$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.
Received
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.
reply
forward
my $rg = Mail::Message::Head::ResentGroup->new(head => $head, ...); $head->addResentGroup($rg); my $rg = $head->addResentGroup(From => 'me');
$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.
$obj->get(NAME [,INDEX])
See "Access to the header" in Mail::Message::Head
$obj->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.
print $head->grepNames(); # same as $head->names print $head->grepNames('X-', 'Subject', '); print $head->grepNames('To\b'); # will only select To
$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.
$head->print(\*OUT); $head->print; my $fh = IO::File->new(...); $head->print($fh);
$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.
Bcc
Resent-Bcc
$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.
$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->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->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.
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.
Resent-
Resent
Return-Path
$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.
For Received fields, you should take a look at resent groups, as implemented in Mail::Message::Head::ResentGroup. Removing those lines without their related lines is not a smart idea. Read the details Mail::Message::Head::ResentGroup::delete().
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.
# 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.
set
$obj->string
Returns the whole header as one scalar (in scalar context) or list of lines (list context). Triggers completion.
$obj->guessBodySize
See "About the body" in Mail::Message::Head
$obj->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::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
$obj->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.
time
gmtime
localtime
$obj->addNoRealize(FIELD)
See "Internals" in Mail::Message::Head
$obj->addOrderedFields(FIELDS)
$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.
From
$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
$obj->load
$obj->messageIdPrefix([STRING])
Sets/returns the message-id start. The rest of the message-id is an integer which is derived from the current time and the local host. See createMessageId().
$obj->moveLocation(DISTANCE)
$obj->read(PARSER)
$obj->setNoRealize(FIELD)
$obj->AUTOLOAD
See "Error handling" in Mail::Reporter
$obj->defaultTrace([LEVEL, [LEVEL])
Mail::Message::Head::Complete->defaultTrace([LEVEL, [LEVEL])
$obj->errors
$obj->log([LEVEL [,STRINGS]])
Mail::Message::Head::Complete->log([LEVEL [,STRINGS]])
$obj->logPriority(LEVEL)
Mail::Message::Head::Complete->logPriority(LEVEL)
$obj->logSettings
$obj->notImplemented
$obj->report([LEVEL])
$obj->reportAll([LEVEL])
$obj->trace([LEVEL])
$obj->warnings
$obj->DESTROY
See "Cleanup" in Mail::Reporter
$obj->inGlobalDestruction
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.
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 Mail::Box website at http://perl.overmeer.net/mailbox/ for more details.
Module version 2.042. 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.
To install Mail::Box, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mail::Box
CPAN shell
perl -MCPAN -e shell install Mail::Box
For more information on module installation, please visit the detailed CPAN module installation guide.