unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

Mail::Message::ConstruUserRContributed PMail::Message::Construct::Rebuild(3pm)



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.

       o   descendMultiparts (*)

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

       o   descendNested (*)

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

       o   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.

       o   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.

       o   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.

       o   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.

       o   removeEmptyMultiparts

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

       o   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.

       o   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.

       o   removeHtmlAlternativeToText

           When a multipart alternative is encountered, which contains both a
           plain text and an html part, then the html part is flagged for
           deletion.  Especially useful in combination with the
           "removeDeletedParts" and "flattenMultiparts" rules.

       o   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.

       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-Box distribution version 2.082, built on
       April 28, 2008. Website: http://perl.overmeer.net/mailbox/

LICENSE
       Copyrights 2001-2008 by Mark Overmeer. 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://www.perl.com/perl/misc/Artistic.html



perl v5.10.0                      2008-0Mail::Message::Construct::Rebuild(3pm)