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 Modifying an existing message is a complicated job. Not only do you
111 need to know what you are willing to change, but you have to take care
112 about multiparts (possibly nested in multiple levels), rfc822
113 encapsulated messages, header field consistency, and so on. The
114 rebuild() method let you focus on the task, and takes care of the rest.
115 The rebuild() method uses rules to transform the one message into an
117 other. If one or more of the rules apply, a new message will be
118 returned. A simple numeric comparison tells whether the message has
119 changed. For example
120 print "No change"
122 if $message == $message->rebuild;
123 Transformation is made with a set of rules. Each rule performs only a
125 small step, which makes is easily configurable. The rules are ordered,
126 and when one makes a change to the result, the result will be passed to
127 all the rules again until no rule makes a change on the part anymore.
128 A rule may also return "undef" in which case the part will be removed
129 from the (resulting) message.
130 General rules
132 This sections describes the general configuration rules: all quite
134 straight forward transformations on the message structure. The rules
135 marked with (*) are used by default.
136 • descendMultiparts (*)
138 Apply the rules to the parts of (possibly nested) multiparts, not
140 only to the top-level message.
141 • descendNested (*)
143 Apply the rules to the "message/rfc822" encapsulated message as
145 well.
146 • flattenEmptyMultiparts (*)
148 Multipart messages which do not have any parts left are replaced by
150 a single part which contains the preamble, epilogue and a brief
151 explanation.
152 • flattenMultiparts (*)
154 When a multipart contains only one part, that part will take the
156 place of the multipart: the removal of a level of nesting. This
157 way, the preamble and epilogue of the multipart (which do not have
158 a meaning, officially) are lost.
159 • flattenNesting
161 Remove the "message/rfc822" encapsulation. Only the content
163 related lines of the encapsulated body are preserved one level
164 higher. Other information will be lost, which is often not too
165 bad.
166 • removeDeletedParts
168 All parts which are flagged for deletion are removed from the
170 message without leaving a trace. If a nested message is
171 encountered which has its encapsulated content flagged for
172 deletion, it will be removed as a whole.
173 • removeEmptyMultiparts
175 Multipart messages which do not have any parts left are removed.
177 The information in preamble and epiloge is lost.
178 • removeEmptyBodies
180 Simple message bodies which do not contain any lines of content are
182 removed. This will loose the information which is stored in the
183 headers of these bodies.
184 • replaceDeletedParts (*)
186 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
196 content. Please contribute with ideas and implementations.
197 • removeHtmlAlternativeToText
199 When a multipart alternative is encountered, which contains both a
201 plain text and an html part, then the html part is deleted.
202 Especially useful in combination with the "flattenMultiparts" rule.
203 • textAlternativeForHtml
205 Any "text/html" part which is not accompanied by an alternative
207 plain text part will have one added. You must have a working
208 Mail::Message::Convert::HtmlFormatText, which means that
209 HTML::TreeBuilder and HTML::FormatText must be installed on your
210 system.
211 When you are planning to create an automatic html to plain text
213 filter for your email, then have a look at
214 https://github.com/logological/mimestrip
215 . Example: using parameter with "textAlternativeForHtml"
217 my $result = $msg->rebuild
219 ( extra_rules => [ 'textAlternativeForHtml' ]
220 , textAlternativeForHtml => { leftmargin => 0 }
221 );
222 • removeExtraAlternativeText
224 [2.110] When a multipart alternative is encountered, deletes all
226 its parts except for the last part (the preferred part in
227 accordance with RFC2046). In practice, this normally results in the
228 alternative plain text part being deleted of an html message.
229 Useful in combination with the "flattenMultiparts" rule.
230 Adding your own rules
232 If you have designed your own rule, please consider contributing this
234 to Mail::Box; it may be useful for other people as well.
235 Each rule is called
237 my $new = $code->($message, $part, %options)
239 where the %options are defined by the rebuild() method internals. At
241 least the "rules" option is passed, which is a full expansion of all
242 the rules which will be applied.
243 Your subroutine shall return $part if no changes are needed, "undef" if
245 the part should be removed, and any newly constructed
246 "Mail::Message::Part" when a change is required. It is easiest to
247 start looking at the source code of this package, and copy from a
248 comparible routine.
249 When you have your own routine, you simply call:
251 my $rebuild_message = $message->rebuild
253 ( extra_rules => [ \&my_own_rule, 'other_rule' ] );
254
256 Error: No rebuild rule $name defined.
257
259 This module is part of Mail-Message distribution version 3.013, built
260 on June 24, 2023. Website: http://perl.overmeer.net/CPAN/
261
263 Copyrights 2001-2023 by [Mark Overmeer <markov@cpan.org>]. For other
264 contributors see ChangeLog.
265 This program is free software; you can redistribute it and/or modify it
267 under the same terms as Perl itself. See http://dev.perl.org/licenses/
268perl v5.38.0 2023-07-2M0ail::Message::Construct::Rebuild(3)