Provided by: libmail-message-perl_3.012-1_all bug

NAME

       Mail::Message::Construct::Rebuild - modify a Mail::Message

SYNOPSIS

        my $cleanup = $msg->rebuild;

DESCRIPTION

       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.

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' ]
              );

   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.

DETAILS

   Rebuilding a message
       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.

       General rules

       This sections describes the general configuration rules: all quite straight forward
       transformations on the message structure.  The rules marked with (*) are used by default.

       •   descendMultiparts (*)

           Apply the rules to the parts of (possibly nested) multiparts, not only to the top-
           level message.

       •   descendNested (*)

           Apply the rules to the "message/rfc822" encapsulated message as well.

       •   flattenEmptyMultiparts (*)

           Multipart messages which do not have any parts left are replaced by a single part
           which contains the preamble, epilogue and a brief explanation.

       •   flattenMultiparts (*)

           When a multipart contains only one part, that part will take the place of the
           multipart: the removal of a level of nesting.  This way, the preamble and epilogue of
           the multipart (which do not have a meaning, officially) are lost.

       •   flattenNesting

           Remove the "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.

       •   removeDeletedParts

           All parts which are flagged for deletion are removed from the message without leaving
           a trace.  If a nested message is encountered which has its encapsulated content
           flagged for deletion, it will be removed as a whole.

       •   removeEmptyMultiparts

           Multipart messages which do not have any parts left are removed.  The information in
           preamble and epiloge is lost.

       •   removeEmptyBodies

           Simple message bodies which do not contain any lines of content are removed.  This
           will loose the information which is stored in the headers of these bodies.

       •   replaceDeletedParts (*)

           All parts of the message which are flagged for deletion are replace by a message which
           says that the part is deleted.

       You can specify a selection of these rules with rebuild(rules) and rebuild(extra_rules).

       Conversion rules

       This section describes the rules which try to be smart with the content.  Please
       contribute with ideas and implementations.

       •   removeHtmlAlternativeToText

           When a multipart alternative is encountered, which contains both a plain text and an
           html part, then the html part is deleted.  Especially useful in combination with the
           "flattenMultiparts" rule.

       •   textAlternativeForHtml

           Any "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.

           When you are planning to create an automatic html to plain text filter for your email,
           then have a look at https://github.com/logological/mimestrip

           . Example: using parameter with "textAlternativeForHtml"

             my $result = $msg->rebuild
               ( extra_rules => [ 'textAlternativeForHtml' ]
               , textAlternativeForHtml => { leftmargin => 0 }
               );

       •   removeExtraAlternativeText

           [2.110] When a multipart alternative is encountered, deletes all its parts except for
           the last part (the preferred part in accordance with RFC2046). In practice, this
           normally results in the alternative plain text part being deleted of an html message.
           Useful in combination with the "flattenMultiparts" rule.

       Adding your own rules

       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' ] );

DIAGNOSTICS

       Error: No rebuild rule $name defined.

SEE ALSO

       This module is part of Mail-Message distribution version 3.012, built on February 11,
       2022. Website: http://perl.overmeer.net/CPAN/

LICENSE

       Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other contributors see
       ChangeLog.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See http://dev.perl.org/licenses/