
=head1 NAME


Mail::Message::Body::Multipart - body of a message with attachments

=head1 CLASS INHERITANCE

Mail::Message::Body::Multipart
   is a Mail::Message::Body
   is a Mail::Reporter

=head1 SYNOPSIS


 See Mail::Message::Body, plus

 if($body->isMultipart) {
    my @attachments = $body->parts;
    my $attachment3 = $body->part(2);
    my $before      = $body->preamble;
    my $after       = $body->epilogue;
    $body->part(1)->delete;
 }

=head1 DESCRIPTION


The body (content) of a message can be stored in various ways.  In this
manual-page you find the description of extra functionality you have
when a message contains attachments (parts).

=head1 METHODS

=head2 Initiation

=over 4

=item B<new> OPTIONS X<new>

 OPTION               DEFAULT
 based_on             undef
 boundary             undef
 charset              'us-ascii'
 checked              <false>
 data                 undef
 disposition          undef
 eol                  'NATIVE'
 epilogue             undef
 file                 undef
 log                  'WARNINGS'
 message              undef
 mime_type            'multipart/mixed'
 modified             <false>
 parts                undef
 preamble             undef
 trace                'WARNINGS'
 transfer_encoding    'NONE'

=over 4

=item B<based_on> =E<gt> BODY

See Mail::Message::Body::new(based_on)

=item B<boundary> =E<gt> STRING X<new(boundary)>

Separator to be used between parts of the message.  This separator must
be unique in case the message contains nested multiparts (which are not
unusual).  If <undef>, a nice unique boundary will be generated.

=item B<charset> =E<gt> STRING

See Mail::Message::Body::new(charset)

=item B<checked> =E<gt> BOOLEAN

See Mail::Message::Body::new(checked)

=item B<data> =E<gt> ARRAY-OF-LINES | STRING

See Mail::Message::Body::new(data)

=item B<disposition> =E<gt> STRING|FIELD

See Mail::Message::Body::new(disposition)

=item B<eol> =E<gt> 'CR'|'LF'|'CRLF'|'NATIVE'

See Mail::Message::Body::new(eol)

=item B<epilogue> =E<gt> BODY X<new(epilogue)>

The text which is included in the main body after the final boundary.  This
is usually empty, and has no meaning.

=item B<file> =E<gt> FILENAME|FILEHANDLE|IOHANDLE

See Mail::Message::Body::new(file)

=item B<log> =E<gt> LEVEL

See Mail::Reporter::new(log)

=item B<message> =E<gt> MESSAGE

See Mail::Message::Body::new(message)

=item B<mime_type> =E<gt> STRING|FIELD|MIME

See Mail::Message::Body::new(mime_type)

=item B<modified> =E<gt> BOOLEAN

See Mail::Message::Body::new(modified)

=item B<parts> =E<gt> ARRAY-OF-(MESSAGES|BODIES) X<new(parts)>

Specifies an initial list of parts in this body.  These may be full
MESSAGES, or BODIES which transformed into messages before use.  Each
message is coerced into a Mail::Message::Part object.

C<MIME::Entity> and C<Mail::Internet> objects are acceptable in the
list, because they are coercible into Mail::Message::Part's.  Values
of C<undef> will be skipped silently.

=item B<preamble> =E<gt> BODY X<new(preamble)>

The text which is included in the body before the first part.  It is
common use to include a text to warn the user that the message is a
multipart.  However, this was useful in earlier days: most mail
agents are very capable in warning the user themselves.

=item B<trace> =E<gt> LEVEL

See Mail::Reporter::new(trace)

=item B<transfer_encoding> =E<gt> STRING|FIELD

See Mail::Message::Body::new(transfer_encoding)

=back

Examples:

 my $intro = Mail::Message::Body->new(data => ['part one']);
 my $pgp   = Mail::Message::Body->new(data => ['part three']);

 my $body  = Mail::Message::Body::Multipart->new
   ( boundary => time . '--it-s-mine'
   , parts    => [ $intro, $folder->message(3)->decoded, $pgp ]
   );

=back

=head2 The Body

=over 4

=item B<clone> 

See Mail::Message::Body::clone()

=item B<decoded> OPTIONS

See Mail::Message::Body::decoded()

=item B<isDelayed> 

See Mail::Message::Body::isDelayed()

=item B<isMultipart> 

See Mail::Message::Body::isMultipart()

=item B<isNested> 

See Mail::Message::Body::isNested()

=item B<message> [MESSAGE]

See Mail::Message::Body::message()

=item B<modified> [BOOL]

See Mail::Message::Body::modified()

=item B<print> [FILE]

See Mail::Message::Body::print()

=back

=head2 About the Payload

=over 4

=item B<charset> 

See Mail::Message::Body::charset()

=item B<checked> [BOOLEAN]

See Mail::Message::Body::checked()

=item B<disposition> [STRING|FIELD]

See Mail::Message::Body::disposition()

=item B<eol> ['CR'|'LF'|'CRLF'|'NATIVE']

See Mail::Message::Body::eol()

=item B<mimeType> 

See Mail::Message::Body::mimeType()

=item B<nrLines> 

See Mail::Message::Body::nrLines()

=item B<size> 

See Mail::Message::Body::size()

=item B<transferEncoding> [STRING|FIELD]

See Mail::Message::Body::transferEncoding()

=item B<type> 

See Mail::Message::Body::type()

=back

=head2 Access to the Payload

=over 4

=item B<boundary> [STRING] X<boundary>

Returns the boundary which is used to separate the parts in this
body.  If none was read from file, then one will be assigned.  With
STRING you explicitly set the boundary to be used.

=item B<epilogue>  X<epilogue>

Returns the epilogue (the text after the last message part --attachment),
The preamble is stored in a BODY object, and its encoding is derived
from the multipart header.

=item B<file> 

See Mail::Message::Body::file()

=item B<foreachComponent> CODE X<foreachComponent>

Execute the CODE for each component of the message: the preamble, the
epilogue, and each of the parts.

Each component is a body and is passed as second argument to the CODE.
The first argument is a reference to this multi-parted body.  The CODE
returns a body object.  When any of the returned bodies differs from
the body which was passed, then a new multi-part body will be returned.
Reference to the not-changed bodies and the changed bodies will be
included in that new multi-part.

Examples:

 my $checked = $multi->foreachComponent(sub {$_[1]->check});

=item B<lines> 

See Mail::Message::Body::lines()

=item B<part> INDEX X<part>

Returns only the part with the specified INDEX.  You may use a negative
value here, which counts from the back in the list.  Parts which are
flagged to be deleted are included in the count.

Example:

 $message->body->part(2)->print;
 $body->part(1)->delete;

=item B<parts> ['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER] X<parts>

Return all parts by default, or when ALL is specified.  ACTIVE returns
the parts which are not flagged for deletion, as opposite to DELETED.
RECURSE descents into all nested multiparts to collect all parts.

You may also specify a code reference which is called for each nested
part.  The first argument will be the message part.  When the code
returns true, the part is incorporated in the return list.

Examples:

 print "Number of attachments: ",
     scalar $message->body->parts('ACTIVE');

 foreach my $part ($message->body->parts) {
     print "Type: ", $part->get('Content-Type');
 }

=item B<preamble>  X<preamble>

Returns the preamble (the text before the first message part --attachment),
The preamble is stored in a BODY object, and its encoding is derived
from the multipart header.

=item B<string> 

See Mail::Message::Body::string()

=back

=head2 Constructing a Body

=over 4

=item B<attach> MESSAGES|BODIES X<attach>

Attach a list of MESSAGES to this multipart.  A new body is returned.
When you specify BODIES, they will first be translated into
real messages.  C<MIME::Entity> and C<Mail::Internet> objects may be
specified too.  In any case, the parts will be coerced into
Mail::Message::Part's.

=item B<stripSignature> OPTIONS X<stripSignature>

Removes all parts which contains data usually defined as being signature.
The C<MIME::Type> module provides this knowledge.  A new multipart is
returned, containing the remaining parts.  No OPTIONS are defined yet,
although some may be specified, because this method overrules the
C<stripSignature> method for normal bodies.

=back

=head2 Reading and Writing [internals]

=over 4

=item B<AUTOLOAD> 

See Mail::Message::Body::AUTOLOAD()

=item B<fileLocation> [BEGIN,END]

See Mail::Message::Body::fileLocation()

=item B<load> 

See Mail::Message::Body::load()

=item B<moveLocation> [DISTANCE]

See Mail::Message::Body::moveLocation()

=item B<read> PARSER, HEAD, BODYTYPE [,CHARS [,LINES]]

See Mail::Message::Body::read()

=back

=head2 Logging and Tracing

=over 4

=item B<errors> 

See Mail::Reporter::errors()

=item B<log> [LEVEL [,STRINGS]]

See Mail::Reporter::log()

=item B<report> [LEVEL]

See Mail::Reporter::report()

=item B<reportAll> [LEVEL]

See Mail::Reporter::reportAll()

=item B<trace> [LEVEL]

See Mail::Reporter::trace()

=item B<warnings> 

See Mail::Reporter::warnings()

=back

=head2 Other Methods

=over 4

=item B<DESTROY> 

See Mail::Reporter::DESTROY()

=item B<inGlobalDestruction> 

See Mail::Reporter::inGlobalDestruction()

=item B<logPriority> LEVEL

See Mail::Reporter::logPriority()

=item B<logSettings> 

See Mail::Reporter::logSettings()

=item B<notImplemented> 

See Mail::Reporter::notImplemented()

=back

=head1 SEE ALSO

A good start to read is Mail::Box-Overview.
More documentation and a mailinglist are available from the project's
website at L<http://perl.overmeer.net/mailbox/>.

=head1 AUTHOR

Mark Overmeer (L<mark@overmeer.net|mailto:mark@overmeer.net>) with the help of many.

=head1 VERSION

This code is beta, version 2.019.

Copyright (c) 2001-2002 Mark Overmeer. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
