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.
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(extra_rules).
This section describes the rules which try to be smart with the content. Please contribute with ideas and implementations.
flattenMultiparts
rule.
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.
flattenMultiparts
rule.
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 ( extra_rules => [ \&my_own_rule, 'other_rule' ] );