|
Mail::Message::Construct::Rebuild - modify a Mail::Message |
Mail::Message::Construct::Rebuild - modify a Mail::Message
my $cleanup = $msg->rebuild;
Modifying existing messages is a pain, certainly if this has to be done in an automated fashion. The problems are especially had when multiparts have to be created or removed. The rebuild() method tries to simplify this task and add some standard features.
$obj->rebuild(OPTIONS)
Reconstruct an existing message into something new. Returned is a new
message when there were modifications made, undef if the message has
no body left, or the original message when no modifications had to be
made.
Examples of use: you have a message which only contains html, and you want to translate it into a multipart which contains the original html and the textual translation of it. Or, you have a message with parts flagged to be deleted, and you want those changes be incorparted in the memory structure. Another possibility: clear all the resent groups (see Mail::Message::Head::ResentGroup) from the header, before it is written to file.
Reconstructing is a hazardous task, where multi level multiparts and nested messages come into play. The rebuild method tries to simplify handing these messages for you.
Option Defined in Default extraRules [] keep_message_id <false> rules <see text>
. extraRules ARRAY
The standard set of rules, which is the default for the rules option,
is a moderest setting. In stead of copying that list into a full set
of rules of your own, you can also specify only some additional rules
which will be prependend to the default rule set.
The order of the rules is respected, which means that you do not always
need to rewrite the whole rule is (see rule option). For instance,
the extra rule of removeDeletedParts returns an undef, which
means that it cancels the effect of the default rule replaceDeletedParts.
. keep_message_id BOOLEAN
The message-id is an unique identification of the message: no two messages with different content shall exist anywhere. However in practice, when a message is changed during transmission, the id is often incorrectly not changed. This may lead to complications in application which see both messages with the same id.
. rules ARRAY
The ARRAY is a list of rules, which each describe an action which will be called on each part which is found in the message. Most rules probably won't match, but some will bring changes to the content. Rules can be specified as method name, or as code reference. See the DETAILS chapter in this manual page, and recursiveRebuildPart().
By default, only the relatively safe transformations are performed:
replaceDeletedParts, descendMultiparts, descendNested,
flattenMultiparts, flattenEmptyMultiparts. In the future, more
safe transformations may be added to this list.
Example:
# remove all deleted parts my $cleaned = $msg->rebuild(keep_message_id => 1); $folder->addMessage($cleaned) if defined $cleaned;
# Replace deleted parts by a place-holder my $cleaned = $msg->rebuild ( keep_message_id => 1 , extraRules => [ 'removeEmpty', 'flattenMultiparts' ] );
$obj->recursiveRebuildPart(PART, OPTIONS)
Option Defined in Default rules <required>
. rules ARRAY-OF-RULES
Rules are method names which can be called on messages and message parts objects. The ARRAY can also list code references which can be called. In any case, each rule will be called the same way:
$code->(MESSAGE, PART)
The return can be undef or any complex construct based on a
Mail::Message::Part or coerceable into such a part. For each part,
all rules are called in sequence. When a rule returns a changed object,
the rules will start all over again, however undef will immediately
stop it.
Error: no rebuild rule $name defined.
Modifying an existing message is a complicated job. Not only do you need to know what you are willing to change, but you have to take care about multiparts (possibly nested in multiple levels), rfc822 encapsulated messages, header field consistency, and so on. The rebuild() method let you focus on the task, and takes care of the rest.
The rebuild() method uses rules to transform the one message into an other. If one or more of the rules apply, a new message will be returned. A simple numeric comparison tells whether the message has changed. For example
print "No change"
if $message == $message->rebuild;
Transformation is made with a set of rules. Each rule performs only a
small step, which makes is easily configurable. The rules are ordered,
and when one makes a change to the result, the result will be passed
to all the rules again until no rule makes a change on the part anymore.
A rule may also return undef in which case the part will be removed
from the (resulting) message.
This sections describes the general configuration rules: all quite straight forward transformations on the message structure. The rules marked with (*) are used by default.
message/rfc822 encapsulated message as well.
message/rfc822 encapsulation. Only the content related
lines of the encapsulated body are preserved one level higher. Other
information will be lost, which is often not too bad.
You can specify a selection of these rules with rebuild(rules) and rebuild(extraRules).
This section describes the rules which try to be smart with the content. Please contribute with ideas and implementations.
removeDeletedParts
and flattenMultiparts rules.
text/html part which is not accompanied by an alternative
plain text part will have one added. You must have a working
Mail::Message::Convert::HtmlFormatText, which means that
HTML::TreeBuilder and HTML::FormatText must be installed on
your system.
If you have designed your own rule, please consider contributing this to Mail::Box; it may be useful for other people as well.
Each rule is called
my $new = $code->($message, $part, %options)
where the %options are defined by the rebuild() method internals. At
least the rules option is passed, which is a full expansion of all
the rules which will be applied.
Your subroutine shall return $part if no changes are needed,
undef if the part should be removed, and any newly constructed
Mail::Message::Part when a change is required. It is easiest to
start looking at the source code of this package, and copy from a
comparible routine.
When you have your own routine, you simply call:
my $rebuild_message = $message->rebuild ( extraRules => [ \&my_own_rule, 'other_rule' ] );
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::Construct::Rebuild - modify a Mail::Message |