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.