METHODS

Constructing a message

$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 Default

extra_rules

[]

keep_message_id

<false>

rules

<see text>

extra_rules => 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
   , extra_rules => [ 'removeEmpty', 'flattenMultiparts' ]
   );
» Error: No rebuild rule $name defined.

Internals

$obj->recursiveRebuildPart( $part, %options )
Option 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.