1=encoding utf8
2
3=head1 NAME
4
5Mail::Message::Body::Multipart - body of a message with attachments
6
7=head1 INHERITANCE
8
9 Mail::Message::Body::Multipart
10   is a Mail::Message::Body
11   is a Mail::Reporter
12
13=head1 SYNOPSIS
14
15 See Mail::Message::Body
16
17 if($body->isMultipart) {
18    my @attachments = $body->parts;
19    my $attachment3 = $body->part(2);
20    my $before      = $body->preamble;
21    my $after       = $body->epilogue;
22    $body->part(1)->delete;
23 }
24
25=head1 DESCRIPTION
26
27The body (content) of a message can be stored in various ways.  In this
28manual-page you find the description of extra functionality you have
29when a message contains attachments (parts).
30
31Extends L<"DESCRIPTION" in Mail::Message::Body|Mail::Message::Body/"DESCRIPTION">.
32
33=head1 OVERLOADED
34
35Extends L<"OVERLOADED" in Mail::Message::Body|Mail::Message::Body/"OVERLOADED">.
36
37=over 4
38
39=item overload: B<"">
40
41Inherited, see L<Mail::Message::Body/"OVERLOADED">
42
43=item overload: B<'==' and '!='>
44
45Inherited, see L<Mail::Message::Body/"OVERLOADED">
46
47=item overload: B<@{}>
48
49Inherited, see L<Mail::Message::Body/"OVERLOADED">
50
51=item overload: B<bool>
52
53Inherited, see L<Mail::Message::Body/"OVERLOADED">
54
55=back
56
57=head1 METHODS
58
59Extends L<"METHODS" in Mail::Message::Body|Mail::Message::Body/"METHODS">.
60
61=head2 Constructors
62
63Extends L<"Constructors" in Mail::Message::Body|Mail::Message::Body/"Constructors">.
64
65=over 4
66
67=item $obj-E<gt>B<clone>()
68
69Inherited, see L<Mail::Message::Body/"Constructors">
70
71=item Mail::Message::Body::Multipart-E<gt>B<new>(%options)
72
73 -Option           --Defined in         --Default
74  based_on           Mail::Message::Body  undef
75  boundary                                undef
76  charset            Mail::Message::Body  'PERL' or <undef>
77  checked            Mail::Message::Body  <false>
78  content_id         Mail::Message::Body  undef
79  data               Mail::Message::Body  undef
80  description        Mail::Message::Body  undef
81  disposition        Mail::Message::Body  undef
82  eol                Mail::Message::Body  'NATIVE'
83  epilogue                                ''
84  file               Mail::Message::Body  undef
85  filename           Mail::Message::Body  undef
86  log                Mail::Reporter       'WARNINGS'
87  message            Mail::Message::Body  undef
88  mime_type          Mail::Message::Body  'multipart/mixed'
89  modified           Mail::Message::Body  <false>
90  parts                                   undef
91  preamble                                undef
92  trace              Mail::Reporter       'WARNINGS'
93  transfer_encoding  Mail::Message::Body  'none'
94
95=over 2
96
97=item based_on => BODY
98
99=item boundary => STRING
100
101Separator to be used between parts of the message.  This separator must
102be unique in case the message contains nested multiparts (which are not
103unusual).  If C<undef>, a nice unique boundary will be generated.
104
105=item charset => CHARSET|'PERL'
106
107=item checked => BOOLEAN
108
109=item content_id => STRING
110
111=item data => ARRAY-OF-LINES | STRING
112
113=item description => STRING|FIELD
114
115=item disposition => STRING|FIELD
116
117=item eol => 'CR'|'LF'|'CRLF'|'NATIVE'
118
119=item epilogue => BODY|STRING
120
121The text which is included in the main body after the final boundary.  This
122is usually empty, and has no meaning.
123
124Provide a BODY object or a STRING which will automatically translated
125into a C<text/plain> body.
126
127=item file => FILENAME|FILEHANDLE|IOHANDLE
128
129=item filename => FILENAME
130
131=item log => LEVEL
132
133=item message => MESSAGE
134
135=item mime_type => STRING|FIELD|MIME
136
137=item modified => BOOLEAN
138
139=item parts => ARRAY-OF-(MESSAGES|BODIES)
140
141Specifies an initial list of parts in this body.  These may be full
142MESSAGES, or BODIES which transformed into messages before use.  Each
143message is coerced into a L<Mail::Message::Part|Mail::Message::Part> object.
144
145MIME::Entity and L<Mail::Internet|Mail::Internet> objects are acceptable in the
146list, because they are coercible into L<Mail::Message::Part|Mail::Message::Part>'s.  Values
147of C<undef> will be skipped silently.
148
149=item preamble => BODY|STRING
150
151The text which is included in the body before the first part.  It is
152common use to include a text to warn the user that the message is a
153multipart.  However, this was useful in earlier days: most mail
154agents are very capable in warning the user themselves.
155
156Provide a BODY object or a STRING which will automatically translated
157into a text/plain body.
158
159=item trace => LEVEL
160
161=item transfer_encoding => STRING|FIELD
162
163=back
164
165example:
166
167 my $intro = Mail::Message::Body->new(data => ['part one']);
168 my $pgp   = Mail::Message::Body->new(data => ['part three']);
169
170 my $body  = Mail::Message::Body::Multipart->new
171   ( boundary => time . '--it-s-mine'
172   , preamble => "This is a multi-part message in MIME format.\n\n"
173   , parts    => [ $intro, $folder->message(3)->decoded, $pgp ]
174   );
175
176=back
177
178=head2 Constructing a body
179
180Extends L<"Constructing a body" in Mail::Message::Body|Mail::Message::Body/"Constructing a body">.
181
182=over 4
183
184=item $obj-E<gt>B<attach>($messages|$bodies)
185
186Attach a list of $messages to this multipart.  A new body is returned.
187When you specify $bodies, they will first be translated into
188real messages.  MIME::Entity and L<Mail::Internet|Mail::Internet> objects may be
189specified too.  In any case, the parts will be coerced into
190L<Mail::Message::Part|Mail::Message::Part>'s.
191
192=item $obj-E<gt>B<check>()
193
194Inherited, see L<Mail::Message::Body::Encode/"Constructing a body">
195
196=item $obj-E<gt>B<concatenate>($components)
197
198Inherited, see L<Mail::Message::Body::Construct/"Constructing a body">
199
200=item $obj-E<gt>B<decoded>(%options)
201
202Inherited, see L<Mail::Message::Body/"Constructing a body">
203
204=item $obj-E<gt>B<encode>(%options)
205
206Inherited, see L<Mail::Message::Body::Encode/"Constructing a body">
207
208=item $obj-E<gt>B<encoded>()
209
210Inherited, see L<Mail::Message::Body::Encode/"Constructing a body">
211
212=item $obj-E<gt>B<eol>( ['CR'|'LF'|'CRLF'|'NATIVE'] )
213
214Inherited, see L<Mail::Message::Body/"Constructing a body">
215
216=item $obj-E<gt>B<foreachComponent>(CODE)
217
218Execute the CODE for each component of the message: the preamble, the
219epilogue, and each of the parts.
220
221Each component is a body and is passed as second argument to the CODE.
222The first argument is a reference to this multi-parted body.  The CODE
223returns a body object.  When any of the returned bodies differs from
224the body which was passed, then a new multi-part body will be returned.
225Reference to the not-changed bodies and the changed bodies will be
226included in that new multi-part.
227
228example:
229
230 my $checked = $multi->foreachComponent(sub {$_[1]->check});
231
232=item $obj-E<gt>B<foreachLine>((CODE))
233
234It is NOT possible to call some code for each line of a multipart,
235because that would not only inflict damage to the body of each
236message part, but also to the headers and the part separators.
237
238=item $obj-E<gt>B<stripSignature>(%options)
239
240Removes all parts which contains data usually defined as being signature.
241The L<MIME::Type|MIME::Type> module provides this knowledge.  A new multipart is
242returned, containing the remaining parts.  No %options are defined yet,
243although some may be specified, because this method overrules the
244C<stripSignature> method for normal bodies.
245
246 -Option     --Defined in                    --Default
247  max_lines    Mail::Message::Body::Construct  10
248  pattern      Mail::Message::Body::Construct  qr/^--\s?$/
249  result_type  Mail::Message::Body::Construct  <same as current>
250
251=over 2
252
253=item max_lines => INTEGER|undef
254
255=item pattern => REGEX|STRING|CODE
256
257=item result_type => CLASS
258
259=back
260
261=item $obj-E<gt>B<unify>($body)
262
263Inherited, see L<Mail::Message::Body::Encode/"Constructing a body">
264
265=back
266
267=head2 The body
268
269Extends L<"The body" in Mail::Message::Body|Mail::Message::Body/"The body">.
270
271=over 4
272
273=item $obj-E<gt>B<isDelayed>()
274
275Inherited, see L<Mail::Message::Body/"The body">
276
277=item $obj-E<gt>B<isMultipart>()
278
279Inherited, see L<Mail::Message::Body/"The body">
280
281=item $obj-E<gt>B<isNested>()
282
283Inherited, see L<Mail::Message::Body/"The body">
284
285=item $obj-E<gt>B<message>( [$message] )
286
287Inherited, see L<Mail::Message::Body/"The body">
288
289=item $obj-E<gt>B<partNumberOf>($part)
290
291Inherited, see L<Mail::Message::Body/"The body">
292
293=back
294
295=head2 About the payload
296
297Extends L<"About the payload" in Mail::Message::Body|Mail::Message::Body/"About the payload">.
298
299=over 4
300
301=item $obj-E<gt>B<charset>()
302
303Inherited, see L<Mail::Message::Body/"About the payload">
304
305=item $obj-E<gt>B<checked>( [BOOLEAN] )
306
307Inherited, see L<Mail::Message::Body/"About the payload">
308
309=item $obj-E<gt>B<contentId>( [STRING|$field] )
310
311Inherited, see L<Mail::Message::Body/"About the payload">
312
313=item $obj-E<gt>B<description>( [STRING|$field] )
314
315Inherited, see L<Mail::Message::Body/"About the payload">
316
317=item $obj-E<gt>B<disposition>( [STRING|$field] )
318
319Inherited, see L<Mail::Message::Body/"About the payload">
320
321=item $obj-E<gt>B<dispositionFilename>( [$directory] )
322
323Inherited, see L<Mail::Message::Body::Encode/"About the payload">
324
325=item $obj-E<gt>B<isBinary>()
326
327Inherited, see L<Mail::Message::Body::Encode/"About the payload">
328
329=item $obj-E<gt>B<isText>()
330
331Inherited, see L<Mail::Message::Body::Encode/"About the payload">
332
333=item $obj-E<gt>B<mimeType>()
334
335Inherited, see L<Mail::Message::Body/"About the payload">
336
337=item $obj-E<gt>B<nrLines>()
338
339Inherited, see L<Mail::Message::Body/"About the payload">
340
341=item $obj-E<gt>B<size>()
342
343Inherited, see L<Mail::Message::Body/"About the payload">
344
345=item $obj-E<gt>B<transferEncoding>( [STRING|$field] )
346
347Inherited, see L<Mail::Message::Body/"About the payload">
348
349=item $obj-E<gt>B<type>( [STRING|$field] )
350
351Inherited, see L<Mail::Message::Body/"About the payload">
352
353=back
354
355=head2 Access to the payload
356
357Extends L<"Access to the payload" in Mail::Message::Body|Mail::Message::Body/"Access to the payload">.
358
359=over 4
360
361=item $obj-E<gt>B<boundary>( [STRING] )
362
363Returns the boundary which is used to separate the parts in this
364body.  If none was read from file, then one will be assigned.  With
365STRING you explicitly set the boundary to be used.
366
367=item $obj-E<gt>B<endsOnNewline>()
368
369Inherited, see L<Mail::Message::Body/"Access to the payload">
370
371=item $obj-E<gt>B<epilogue>()
372
373Returns the epilogue; the text after the last message part (after the
374last real attachment).
375The epilogue is stored in a BODY object, and its encoding is taken
376from the general multipart header.
377
378=item $obj-E<gt>B<file>()
379
380Inherited, see L<Mail::Message::Body/"Access to the payload">
381
382=item $obj-E<gt>B<lines>()
383
384Inherited, see L<Mail::Message::Body/"Access to the payload">
385
386=item $obj-E<gt>B<part>($index)
387
388Returns only the part with the specified $index.  You may use a negative
389value here, which counts from the back in the list.  Parts which are
390flagged to be deleted are included in the count.
391
392example:
393
394 $message->body->part(2)->print;
395 $body->part(1)->delete;
396
397=item $obj-E<gt>B<parts>( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] )
398
399Return all parts by default, or when ALL is specified.  C<ACTIVE> returns
400the parts which are not flagged for deletion, as opposite to C<DELETED>.
401C<RECURSE> descents into all nested multiparts to collect all parts.
402
403You may also specify a code reference which is called for each nested
404part.  The first argument will be the message part.  When the code
405returns true, the part is incorporated in the return list.
406
407example:
408
409 print "Number of attachments: ",
410     scalar $message->body->parts('ACTIVE');
411
412 foreach my $part ($message->body->parts) {
413     print "Type: ", $part->get('Content-Type');
414 }
415
416=item $obj-E<gt>B<preamble>()
417
418Returns the preamble; the text before the first message part (before the
419first real attachment).
420The preamble is stored in a BODY object, and its encoding is taken
421from the multipart header.
422
423=item $obj-E<gt>B<print>( [$fh] )
424
425Inherited, see L<Mail::Message::Body/"Access to the payload">
426
427=item $obj-E<gt>B<printEscapedFrom>($fh)
428
429Inherited, see L<Mail::Message::Body/"Access to the payload">
430
431=item $obj-E<gt>B<string>()
432
433Inherited, see L<Mail::Message::Body/"Access to the payload">
434
435=item $obj-E<gt>B<stripTrailingNewline>()
436
437Inherited, see L<Mail::Message::Body/"Access to the payload">
438
439=item $obj-E<gt>B<write>(%options)
440
441Inherited, see L<Mail::Message::Body/"Access to the payload">
442
443=back
444
445=head2 Internals
446
447Extends L<"Internals" in Mail::Message::Body|Mail::Message::Body/"Internals">.
448
449=over 4
450
451=item $obj-E<gt>B<addTransferEncHandler>( $name, <$class|$object> )
452
453=item Mail::Message::Body::Multipart-E<gt>B<addTransferEncHandler>( $name, <$class|$object> )
454
455Inherited, see L<Mail::Message::Body::Encode/"Internals">
456
457=item $obj-E<gt>B<contentInfoFrom>($head)
458
459Inherited, see L<Mail::Message::Body/"Internals">
460
461=item $obj-E<gt>B<contentInfoTo>($head)
462
463Inherited, see L<Mail::Message::Body/"Internals">
464
465=item $obj-E<gt>B<fileLocation>( [$begin, $end] )
466
467Inherited, see L<Mail::Message::Body/"Internals">
468
469=item $obj-E<gt>B<getTransferEncHandler>($type)
470
471Inherited, see L<Mail::Message::Body::Encode/"Internals">
472
473=item $obj-E<gt>B<isModified>()
474
475Inherited, see L<Mail::Message::Body/"Internals">
476
477=item $obj-E<gt>B<load>()
478
479Inherited, see L<Mail::Message::Body/"Internals">
480
481=item $obj-E<gt>B<modified>( [BOOLEAN] )
482
483Inherited, see L<Mail::Message::Body/"Internals">
484
485=item $obj-E<gt>B<moveLocation>( [$distance] )
486
487Inherited, see L<Mail::Message::Body/"Internals">
488
489=item $obj-E<gt>B<read>( $parser, $head, $bodytype, [$chars, [$lines]] )
490
491Inherited, see L<Mail::Message::Body/"Internals">
492
493=back
494
495=head2 Error handling
496
497Extends L<"Error handling" in Mail::Message::Body|Mail::Message::Body/"Error handling">.
498
499=over 4
500
501=item $obj-E<gt>B<AUTOLOAD>()
502
503Inherited, see L<Mail::Message::Body/"Error handling">
504
505=item $obj-E<gt>B<addReport>($object)
506
507Inherited, see L<Mail::Reporter/"Error handling">
508
509=item $obj-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
510
511=item Mail::Message::Body::Multipart-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
512
513Inherited, see L<Mail::Reporter/"Error handling">
514
515=item $obj-E<gt>B<errors>()
516
517Inherited, see L<Mail::Reporter/"Error handling">
518
519=item $obj-E<gt>B<log>( [$level, [$strings]] )
520
521=item Mail::Message::Body::Multipart-E<gt>B<log>( [$level, [$strings]] )
522
523Inherited, see L<Mail::Reporter/"Error handling">
524
525=item $obj-E<gt>B<logPriority>($level)
526
527=item Mail::Message::Body::Multipart-E<gt>B<logPriority>($level)
528
529Inherited, see L<Mail::Reporter/"Error handling">
530
531=item $obj-E<gt>B<logSettings>()
532
533Inherited, see L<Mail::Reporter/"Error handling">
534
535=item $obj-E<gt>B<notImplemented>()
536
537Inherited, see L<Mail::Reporter/"Error handling">
538
539=item $obj-E<gt>B<report>( [$level] )
540
541Inherited, see L<Mail::Reporter/"Error handling">
542
543=item $obj-E<gt>B<reportAll>( [$level] )
544
545Inherited, see L<Mail::Reporter/"Error handling">
546
547=item $obj-E<gt>B<trace>( [$level] )
548
549Inherited, see L<Mail::Reporter/"Error handling">
550
551=item $obj-E<gt>B<warnings>()
552
553Inherited, see L<Mail::Reporter/"Error handling">
554
555=back
556
557=head2 Cleanup
558
559Extends L<"Cleanup" in Mail::Message::Body|Mail::Message::Body/"Cleanup">.
560
561=over 4
562
563=item $obj-E<gt>B<DESTROY>()
564
565Inherited, see L<Mail::Reporter/"Cleanup">
566
567=back
568
569=head1 DETAILS
570
571Extends L<"DETAILS" in Mail::Message::Body|Mail::Message::Body/"DETAILS">.
572
573=head1 DIAGNOSTICS
574
575=over 4
576
577=item Warning: Charset $name is not known
578
579The encoding or decoding of a message body encounters a character set which
580is not understood by Perl's Encode module.
581
582=item Error: Data not convertible to a message (type is $type)
583
584An object which is not coercable into a L<Mail::Message::Part|Mail::Message::Part> object was
585passed to the initiation.  The data is ignored.
586
587=item Warning: No decoder defined for transfer encoding $name.
588
589The data (message body) is encoded in a way which is not currently understood,
590therefore no decoding (or recoding) can take place.
591
592=item Warning: No encoder defined for transfer encoding $name.
593
594The data (message body) has been decoded, but the required encoding is
595unknown.  The decoded data is returned.
596
597=item Error: Package $package does not implement $method.
598
599Fatal error: the specific package (or one of its superclasses) does not
600implement this method where it should. This message means that some other
601related classes do implement this method however the class at hand does
602not.  Probably you should investigate this and probably inform the author
603of the package.
604
605=item Error: Unknown criterium $what to select parts.
606
607Valid choices fdr part selections are C<ALL>, C<ACTIVE>, C<DELETED>,
608C<RECURSE> or a code reference.  However, some other argument was passed.
609
610=item Warning: Unknown line terminator $eol ignored
611
612=item Error: You cannot use foreachLine on a multipart
613
614L<foreachLine()|Mail::Message::Body::Multipart/"METHODS"> should be used on decoded message bodies only, because
615it would attempt to modify part-headers and separators as well, which is
616clearly not acceptable.
617
618=back
619
620=head1 SEE ALSO
621
622This module is part of Mail-Message distribution version 3.011,
623built on July 27, 2021. Website: F<http://perl.overmeer.net/CPAN/>
624
625=head1 LICENSE
626
627Copyrights 2001-2021 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
628
629This program is free software; you can redistribute it and/or modify it
630under the same terms as Perl itself.
631See F<http://dev.perl.org/licenses/>
632
633