1Mail::Message::ConstrucUts:e:rReCbounitlrdi(b3u)ted PerlMaDiolc:u:mMeenstsaatgieo:n:Construct::Rebuild(3)
2
6 Mail::Message::Construct::Rebuild - modify a Mail::Message
7
9 my $cleanup = $msg->rebuild;
10
12 Modifying existing messages is a pain, certainly if this has to be done
13 in an automated fashion. The problems are especially had when
14 multiparts have to be created or removed. The rebuild() method tries
15 to simplify this task and add some standard features.
16
18 Constructing a message
19 $obj->rebuild(OPTIONS)
20 Reconstruct an existing message into something new. Returned is a
21 new message when there were modifications made, "undef" if the
22 message has no body left, or the original message when no
23 modifications had to be made.
24 Examples of use: you have a message which only contains html, and
26 you want to translate it into a multipart which contains the
27 original html and the textual translation of it. Or, you have a
28 message with parts flagged to be deleted, and you want those
29 changes be incorparted in the memory structure. Another
30 possibility: clear all the resent groups (see
31 Mail::Message::Head::ResentGroup) from the header, before it is
32 written to file.
33 Reconstructing is a hazardous task, where multi level multiparts
35 and nested messages come into play. The rebuild method tries to
36 simplify handing these messages for you.
37 -Option --Default
39 extra_rules []
40 keep_message_id <false>
41 rules <see text>
42 extra_rules => ARRAY
44 The standard set of rules, which is the default for the "rules"
45 option, is a moderest setting. In stead of copying that list
46 into a full set of rules of your own, you can also specify only
47 some additional rules which will be prependend to the default
48 rule set.
49 The order of the rules is respected, which means that you do not
51 always need to rewrite the whole rule is (see "rule" option).
52 For instance, the extra rule of "removeDeletedParts" returns an
53 "undef", which means that it cancels the effect of the default
54 rule "replaceDeletedParts".
55 keep_message_id => BOOLEAN
57 The message-id is an unique identification of the message: no two
58 messages with different content shall exist anywhere. However in
59 practice, when a message is changed during transmission, the id
60 is often incorrectly not changed. This may lead to complications
61 in application which see both messages with the same id.
62 rules => ARRAY
64 The ARRAY is a list of rules, which each describe an action which
65 will be called on each part which is found in the message. Most
66 rules probably won't match, but some will bring changes to the
67 content. Rules can be specified as method name, or as code
68 reference. See the "DETAILS" chapter in this manual page, and
69 recursiveRebuildPart().
70 By default, only the relatively safe transformations are
72 performed: "replaceDeletedParts", "descendMultiparts",
73 "descendNested", "flattenMultiparts", "flattenEmptyMultiparts".
74 In the future, more safe transformations may be added to this
75 list.
76 example:
78 # remove all deleted parts
80 my $cleaned = $msg->rebuild(keep_message_id => 1);
81 $folder->addMessage($cleaned) if defined $cleaned;
82 # Replace deleted parts by a place-holder
84 my $cleaned = $msg->rebuild
85 ( keep_message_id => 1
86 , extra_rules => [ 'removeEmpty', 'flattenMultiparts' ]
87 );
88 Internals
90 $obj->recursiveRebuildPart(PART, OPTIONS)
91 -Option--Default
92 rules <required>
93 rules => ARRAY-OF-RULES
95 Rules are method names which can be called on messages and
96 message parts objects. The ARRAY can also list code references
97 which can be called. In any case, each rule will be called the
98 same way:
99 $code->(MESSAGE, PART)
101 The return can be "undef" or any complex construct based on a
103 Mail::Message::Part or coerceable into such a part. For each
104 part, all rules are called in sequence. When a rule returns a
105 changed object, the rules will start all over again, however
106 "undef" will immediately stop it.
107
109 Rebuilding a message
110 General rules
111 This sections describes the general configuration rules: all quite
113 straight forward transformations on the message structure. The rules
114 marked with (*) are used by default.
115 · descendMultiparts (*)
117 Apply the rules to the parts of (possibly nested) multiparts, not
119 only to the top-level message.
120 · descendNested (*)
122 Apply the rules to the "message/rfc822" encapsulated message as
124 well.
125 · flattenEmptyMultiparts (*)
127 Multipart messages which do not have any parts left are replaced by
129 a single part which contains the preamble, epilogue and a brief
130 explanation.
131 · flattenMultiparts (*)
133 When a multipart contains only one part, that part will take the
135 place of the multipart: the removal of a level of nesting. This
136 way, the preamble and epilogue of the multipart (which do not have
137 a meaning, officially) are lost.
138 · flattenNesting
140 Remove the "message/rfc822" encapsulation. Only the content
142 related lines of the encapsulated body are preserved one level
143 higher. Other information will be lost, which is often not too
144 bad.
145 · removeDeletedParts
147 All parts which are flagged for deletion are removed from the
149 message without leaving a trace. If a nested message is
150 encountered which has its encapsulated content flagged for
151 deletion, it will be removed as a whole.
152 · removeEmptyMultiparts
154 Multipart messages which do not have any parts left are removed.
156 The information in preamble and epiloge is lost.
157 · removeEmptyBodies
159 Simple message bodies which do not contain any lines of content are
161 removed. This will loose the information which is stored in the
162 headers of these bodies.
163 · replaceDeletedParts (*)
165 All parts of the message which are flagged for deletion are replace
167 by a message which says that the part is deleted.
168 You can specify a selection of these rules with rebuild(rules) and
170 rebuild(extra_rules).
171 Conversion rules
173 This section describes the rules which try to be smart with the
175 content. Please contribute with ideas and implementations.
176 · removeHtmlAlternativeToText
178 When a multipart alternative is encountered, which contains both a
180 plain text and an html part, then the html part is flagged for
181 deletion. Especially useful in combination with the
182 "removeDeletedParts" and "flattenMultiparts" rules.
183 · textAlternativeForHtml
185 Any "text/html" part which is not accompanied by an alternative
187 plain text part will have one added. You must have a working
188 Mail::Message::Convert::HtmlFormatText, which means that
189 HTML::TreeBuilder and HTML::FormatText must be installed on your
190 system.
191 Adding your own rules
193 If you have designed your own rule, please consider contributing this
195 to Mail::Box; it may be useful for other people as well.
196 Each rule is called
198 my $new = $code->($message, $part, %options)
200 where the %options are defined by the "rebuild()" method internals. At
202 least the "rules" option is passed, which is a full expansion of all
203 the rules which will be applied.
204 Your subroutine shall return $part if no changes are needed, "undef" if
206 the part should be removed, and any newly constructed
207 "Mail::Message::Part" when a change is required. It is easiest to
208 start looking at the source code of this package, and copy from a
209 comparible routine.
210 When you have your own routine, you simply call:
212 my $rebuild_message = $message->rebuild
214 ( extra_rules => [ \&my_own_rule, 'other_rule' ] );
215 Modifying an existing message is a complicated job. Not only do you
217 need to know what you are willing to change, but you have to take care
218 about multiparts (possibly nested in multiple levels), rfc822
219 encapsulated messages, header field consistency, and so on. The
220 rebuild() method let you focus on the task, and takes care of the rest.
221 The rebuild() method uses rules to transform the one message into an
223 other. If one or more of the rules apply, a new message will be
224 returned. A simple numeric comparison tells whether the message has
225 changed. For example
226 print "No change"
228 if $message == $message->rebuild;
229 Transformation is made with a set of rules. Each rule performs only a
231 small step, which makes is easily configurable. The rules are ordered,
232 and when one makes a change to the result, the result will be passed to
233 all the rules again until no rule makes a change on the part anymore.
234 A rule may also return "undef" in which case the part will be removed
235 from the (resulting) message.
236
238 Error: No rebuild rule $name defined.
239
241 This module is part of Mail-Box distribution version 2.097, built on
242 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
243
245 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
246 ChangeLog.
247 This program is free software; you can redistribute it and/or modify it
249 under the same terms as Perl itself. See
250 http://www.perl.com/perl/misc/Artistic.html
251perl v5.12.3 2011-01-2M6ail::Message::Construct::Rebuild(3)