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 multi‐
14 parts have to be created or removed. The rebuild() method tries to
15 simplify this task and add some standard features.
16
18 Constructing a message
19 $obj->rebuild(OPTIONS)
21 Reconstruct an existing message into something new. Returned is a
23 new message when there were modifications made, "undef" if the mes‐
24 sage has no body left, or the original message when no modifica‐
25 tions had to be made.
26 Examples of use: you have a message which only contains html, and
28 you want to translate it into a multipart which contains the origi‐
29 nal html and the textual translation of it. Or, you have a message
30 with parts flagged to be deleted, and you want those changes be
31 incorparted in the memory structure. Another possibility: clear
32 all the resent groups (see Mail::Message::Head::ResentGroup) from
33 the header, before it is written to file.
34 Reconstructing is a hazardous task, where multi level multiparts
36 and nested messages come into play. The rebuild method tries to
37 simplify handing these messages for you.
38 Option --Default
40 extra_rules []
41 keep_message_id <false>
42 rules <see text>
43 . extra_rules ARRAY
45 The standard set of rules, which is the default for the "rules"
47 option, is a moderest setting. In stead of copying that list
48 into a full set of rules of your own, you can also specify only
49 some additional rules which will be prependend to the default
50 rule set.
51 The order of the rules is respected, which means that you do
53 not always need to rewrite the whole rule is (see "rule"
54 option). For instance, the extra rule of "removeDeletedParts"
55 returns an "undef", which means that it cancels the effect of
56 the default rule "replaceDeletedParts".
57 . keep_message_id BOOLEAN
59 The message-id is an unique identification of the message: no
61 two messages with different content shall exist anywhere. How‐
62 ever in practice, when a message is changed during transmis‐
63 sion, the id is often incorrectly not changed. This may lead
64 to complications in application which see both messages with
65 the same id.
66 . rules ARRAY
68 The ARRAY is a list of rules, which each describe an action
70 which will be called on each part which is found in the mes‐
71 sage. Most rules probably won't match, but some will bring
72 changes to the content. Rules can be specified as method name,
73 or as code reference. See the "DETAILS" chapter in this manual
74 page, and recursiveRebuildPart().
75 By default, only the relatively safe transformations are per‐
77 formed: "replaceDeletedParts", "descendMultiparts",
78 "descendNested", "flattenMultiparts", "flattenEmptyMultiparts".
79 In the future, more safe transformations may be added to this
80 list.
81 Example:
83 # remove all deleted parts
85 my $cleaned = $msg->rebuild(keep_message_id => 1);
86 $folder->addMessage($cleaned) if defined $cleaned;
87 # Replace deleted parts by a place-holder
89 my $cleaned = $msg->rebuild
90 ( keep_message_id => 1
91 , extra_rules => [ 'removeEmpty', 'flattenMultiparts' ]
92 );
93 Internals
95 $obj->recursiveRebuildPart(PART, OPTIONS)
97 Option--Default
99 rules <required>
100 . rules ARRAY-OF-RULES
102 Rules are method names which can be called on messages and mes‐
104 sage parts objects. The ARRAY can also list code references
105 which can be called. In any case, each rule will be called the
106 same way:
107 $code->(MESSAGE, PART)
109 The return can be "undef" or any complex construct based on a
111 Mail::Message::Part or coerceable into such a part. For each
112 part, all rules are called in sequence. When a rule returns a
113 changed object, the rules will start all over again, however
114 "undef" will immediately stop it.
115
117 Rebuilding a message
118 Modifying an existing message is a complicated job. Not only do you
120 need to know what you are willing to change, but you have to take care
121 about multiparts (possibly nested in multiple levels), rfc822 encapsu‐
122 lated messages, header field consistency, and so on. The rebuild()
123 method let you focus on the task, and takes care of the rest.
124 The rebuild() method uses rules to transform the one message into an
126 other. If one or more of the rules apply, a new message will be
127 returned. A simple numeric comparison tells whether the message has
128 changed. For example
129 print "No change"
131 if $message == $message->rebuild;
132 Transformation is made with a set of rules. Each rule performs only a
134 small step, which makes is easily configurable. The rules are ordered,
135 and when one makes a change to the result, the result will be passed to
136 all the rules again until no rule makes a change on the part anymore.
137 A rule may also return "undef" in which case the part will be removed
138 from the (resulting) message.
139 General rules
141 This sections describes the general configuration rules: all quite
143 straight forward transformations on the message structure. The rules
144 marked with (*) are used by default.
145 * descendMultiparts (*)
147 Apply the rules to the parts of (possibly nested) multiparts, not
148 only to the top-level message.
149 * descendNested (*)
151 Apply the rules to the "message/rfc822" encapsulated message as
152 well.
153 * flattenEmptyMultiparts (*)
155 Multipart messages which do not have any parts left are replaced by
156 a single part which contains the preamble, epilogue and a brief
157 explanation.
158 * flattenMultiparts (*)
160 When a multipart contains only one part, that part will take the
161 place of the multipart: the removal of a level of nesting. This
162 way, the preamble and epilogue of the multipart (which do not have
163 a meaning, officially) are lost.
164 * flattenNesting
166 Remove the "message/rfc822" encapsulation. Only the content
167 related lines of the encapsulated body are preserved one level
168 higher. Other information will be lost, which is often not too
169 bad.
170 * removeDeletedParts
172 All parts which are flagged for deletion are removed from the mes‐
173 sage without leaving a trace. If a nested message is encountered
174 which has its encapsulated content flagged for deletion, it will be
175 removed as a whole.
176 * removeEmptyMultiparts
178 Multipart messages which do not have any parts left are removed.
179 The information in preamble and epiloge is lost.
180 * removeEmptyBodies
182 Simple message bodies which do not contain any lines of content are
183 removed. This will loose the information which is stored in the
184 headers of these bodies.
185 * replaceDeletedParts (*)
187 All parts of the message which are flagged for deletion are replace
188 by a message which says that the part is deleted.
189 You can specify a selection of these rules with rebuild(rules) and
191 rebuild(extra_rules).
192 Conversion rules
194 This section describes the rules which try to be smart with the con‐
196 tent. Please contribute with ideas and implementations.
197 * removeHtmlAlternativeToText
199 When a multipart alternative is encountered, which contains both a
200 plain text and an html part, then the html part is flagged for
201 deletion. Especially useful in combination with the "removeDelet‐
202 edParts" and "flattenMultiparts" rules.
203 * textAlternativeForHtml
205 Any "text/html" part which is not accompanied by an alternative
206 plain text part will have one added. You must have a working
207 Mail::Message::Convert::HtmlFormatText, which means that
208 HTML::TreeBuilder and HTML::FormatText must be installed on your
209 system.
210 Adding your own rules
212 If you have designed your own rule, please consider contributing this
214 to Mail::Box; it may be useful for other people as well.
215 Each rule is called
217 my $new = $code->($message, $part, %options)
219 where the %options are defined by the "rebuild()" method internals. At
221 least the "rules" option is passed, which is a full expansion of all
222 the rules which will be applied.
223 Your subroutine shall return $part if no changes are needed, "undef" if
225 the part should be removed, and any newly constructed "Mail::Mes‐
226 sage::Part" when a change is required. It is easiest to start looking
227 at the source code of this package, and copy from a comparible routine.
228 When you have your own routine, you simply call:
230 my $rebuild_message = $message->rebuild
232 ( extra_rules => [ \&my_own_rule, 'other_rule' ] );
233
235 Error: No rebuild rule $name defined.
236
238 This module is part of Mail-Box distribution version 2.070, built on
239 March 25, 2007. Website: http://perl.overmeer.net/mailbox/
240
242 Copyrights 2001-2007 by Mark Overmeer.For other contributors see
243 ChangeLog.
244 This program is free software; you can redistribute it and/or modify it
246 under the same terms as Perl itself. See
247 http://www.perl.com/perl/misc/Artistic.html
248perl v5.8.8 2007-03-2M5ail::Message::Construct::Rebuild(3)