1Mail::Message::ConstrucUts:e:rReCbounitlrdi(b3u)ted PerlMaDiolc:u:mMeenstsaatgieo:n:Construct::Rebuild(3)
2
3
4

NAME

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

SYNOPSIS

9        my $cleanup = $msg->rebuild;
10

DESCRIPTION

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

METHODS

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
25           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
34           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
38            -Option         --Default
39             extra_rules      []
40             keep_message_id  <false>
41             rules            <see text>
42
43           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
50             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
56           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
63           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
71             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
77           example:
78
79            # remove all deleted parts
80            my $cleaned = $msg->rebuild(keep_message_id => 1);
81            $folder->addMessage($cleaned) if defined $cleaned;
82
83            # Replace deleted parts by a place-holder
84            my $cleaned = $msg->rebuild
85              ( keep_message_id => 1
86              , extra_rules => [ 'removeEmpty', 'flattenMultiparts' ]
87              );
88
89   Internals
90       $obj->recursiveRebuildPart($part, %options)
91            -Option--Default
92             rules   <required>
93
94           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
100              $code->(MESSAGE, PART)
101
102             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

DETAILS

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
116       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
121        print "No change"
122           if $message == $message->rebuild;
123
124       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
131       General rules
132
133       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
137       •   descendMultiparts (*)
138
139           Apply the rules to the parts of (possibly nested) multiparts, not
140           only to the top-level message.
141
142       •   descendNested (*)
143
144           Apply the rules to the "message/rfc822" encapsulated message as
145           well.
146
147       •   flattenEmptyMultiparts (*)
148
149           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
153       •   flattenMultiparts (*)
154
155           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
160       •   flattenNesting
161
162           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
167       •   removeDeletedParts
168
169           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
174       •   removeEmptyMultiparts
175
176           Multipart messages which do not have any parts left are removed.
177           The information in preamble and epiloge is lost.
178
179       •   removeEmptyBodies
180
181           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
185       •   replaceDeletedParts (*)
186
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
190       You can specify a selection of these rules with rebuild(rules) and
191       rebuild(extra_rules).
192
193       Conversion rules
194
195       This section describes the rules which try to be smart with the
196       content.  Please contribute with ideas and implementations.
197
198       •   removeHtmlAlternativeToText
199
200           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
204       •   textAlternativeForHtml
205
206           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
212           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
216           . Example: using parameter with "textAlternativeForHtml"
217
218             my $result = $msg->rebuild
219               ( extra_rules => [ 'textAlternativeForHtml' ]
220               , textAlternativeForHtml => { leftmargin => 0 }
221               );
222
223       •   removeExtraAlternativeText
224
225           [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
231       Adding your own rules
232
233       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
236       Each rule is called
237
238        my $new = $code->($message, $part, %options)
239
240       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
244       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
250       When you have your own routine, you simply call:
251
252        my $rebuild_message = $message->rebuild
253         ( extra_rules => [ \&my_own_rule, 'other_rule' ] );
254

DIAGNOSTICS

256       Error: No rebuild rule $name defined.
257

SEE ALSO

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

LICENSE

263       Copyrights 2001-2023 by [Mark Overmeer <markov@cpan.org>]. For other
264       contributors see ChangeLog.
265
266       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/
268
269
270
271perl v5.38.0                      2023-07-2M0ail::Message::Construct::Rebuild(3)
Impressum