Provided by: libmail-box-perl_2.110-1_all bug

NAME

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

INHERITANCE

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

SYNOPSIS

        See Mail::Message::Body

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

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).

       See documentation in the base class.

OVERLOADED

       See documentation in the base class.

       overload: ""()
           See "OVERLOADED" in Mail::Message::Body

       overload: '==' and '!='()
           See "OVERLOADED" in Mail::Message::Body

       overload: @{}()
           See "OVERLOADED" in Mail::Message::Body

       overload: bool()
           See "OVERLOADED" in Mail::Message::Body

METHODS

       See documentation in the base class.

   Constructors
       See documentation in the base class.

       $obj->clone()
           See "Constructors" in Mail::Message::Body

       Mail::Message::Body::Multipart->new(OPTIONS)
            -Option           --Defined in         --Default
             based_on           Mail::Message::Body  undef
             boundary                                undef
             charset            Mail::Message::Body  'PERL' or <undef>
             checked            Mail::Message::Body  <false>
             content_id         Mail::Message::Body  undef
             data               Mail::Message::Body  undef
             description        Mail::Message::Body  undef
             disposition        Mail::Message::Body  undef
             eol                Mail::Message::Body  'NATIVE'
             epilogue                                ''
             file               Mail::Message::Body  undef
             log                Mail::Reporter       'WARNINGS'
             message            Mail::Message::Body  undef
             mime_type          Mail::Message::Body  'multipart/mixed'
             modified           Mail::Message::Body  <false>
             parts                                   undef
             preamble                                undef
             trace              Mail::Reporter       'WARNINGS'
             transfer_encoding  Mail::Message::Body  'none'

           based_on => BODY
           boundary => STRING
             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.

           charset => CHARSET|'PERL'
           checked => BOOLEAN
           content_id => STRING
           data => ARRAY-OF-LINES | STRING
           description => STRING|FIELD
           disposition => STRING|FIELD
           eol => 'CR'|'LF'|'CRLF'|'NATIVE'
           epilogue => BODY|STRING
             The text which is included in the main body after the final boundary.  This is
             usually empty, and has no meaning.

             Provide a BODY object or a STRING which will automatically translated into a
             "text/plain" body.

           file => FILENAME|FILEHANDLE|IOHANDLE
           log => LEVEL
           message => MESSAGE
           mime_type => STRING|FIELD|MIME
           modified => BOOLEAN
           parts => ARRAY-OF-(MESSAGES|BODIES)
             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.

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

           preamble => BODY|STRING
             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.

             Provide a BODY object or a STRING which will automatically translated into a
             text/plain body.

           trace => LEVEL
           transfer_encoding => STRING|FIELD

           example:

            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'
              , preamble => "This is a multi-part message in MIME format.\n\n"
              , parts    => [ $intro, $folder->message(3)->decoded, $pgp ]
              );

   Constructing a body
       See documentation in the base class.

       $obj->attach(MESSAGES|BODIES)
           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.  MIME::Entity and
           Mail::Internet objects may be specified too.  In any case, the parts will be coerced
           into Mail::Message::Part's.

       $obj->check()
           See "Constructing a body" in Mail::Message::Body::Encode

       $obj->concatenate(COMPONENTS)
           See "Constructing a body" in Mail::Message::Body::Construct

       $obj->decoded(OPTIONS)
           See "Constructing a body" in Mail::Message::Body

       $obj->encode(OPTIONS)
           See "Constructing a body" in Mail::Message::Body::Encode

       $obj->encoded()
           See "Constructing a body" in Mail::Message::Body::Encode

       $obj->eol(['CR'|'LF'|'CRLF'|'NATIVE'])
           See "Constructing a body" in Mail::Message::Body

       $obj->foreachComponent(CODE)
           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.

           example:

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

       $obj->foreachLine((CODE))
           It is NOT possible to call some code for each line of a multipart, because that would
           not only inflict damage to the body of each message part, but also to the headers and
           the part separators.

       $obj->stripSignature(OPTIONS)
           Removes all parts which contains data usually defined as being signature.  The
           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 "stripSignature" method for normal bodies.

            -Option     --Defined in                    --Default
             max_lines    Mail::Message::Body::Construct  10
             pattern      Mail::Message::Body::Construct  qr/^--\s?$/
             result_type  Mail::Message::Body::Construct  <same as current>

           max_lines => INTEGER|undef
           pattern => REGEX|STRING|CODE
           result_type => CLASS
       $obj->unify(BODY)
           See "Constructing a body" in Mail::Message::Body::Encode

   The body
       See documentation in the base class.

       $obj->isDelayed()
           See "The body" in Mail::Message::Body

       $obj->isMultipart()
           See "The body" in Mail::Message::Body

       $obj->isNested()
           See "The body" in Mail::Message::Body

       $obj->message([MESSAGE])
           See "The body" in Mail::Message::Body

       $obj->partNumberOf(PART)
           See "The body" in Mail::Message::Body

   About the payload
       See documentation in the base class.

       $obj->charset()
           See "About the payload" in Mail::Message::Body

       $obj->checked([BOOLEAN])
           See "About the payload" in Mail::Message::Body

       $obj->contentId([STRING|FIELD])
           See "About the payload" in Mail::Message::Body

       $obj->description([STRING|FIELD])
           See "About the payload" in Mail::Message::Body

       $obj->disposition([STRING|FIELD])
           See "About the payload" in Mail::Message::Body

       $obj->dispositionFilename([DIRECTORY])
           See "About the payload" in Mail::Message::Body::Encode

       $obj->isBinary()
           See "About the payload" in Mail::Message::Body::Encode

       $obj->isText()
           See "About the payload" in Mail::Message::Body::Encode

       $obj->mimeType()
           See "About the payload" in Mail::Message::Body

       $obj->nrLines()
           See "About the payload" in Mail::Message::Body

       $obj->size()
           See "About the payload" in Mail::Message::Body

       $obj->transferEncoding([STRING|FIELD])
           See "About the payload" in Mail::Message::Body

       $obj->type([STRING|FIELD])
           See "About the payload" in Mail::Message::Body

   Access to the payload
       See documentation in the base class.

       $obj->boundary([STRING])
           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.

       $obj->endsOnNewline()
           See "Access to the payload" in Mail::Message::Body

       $obj->epilogue()
           Returns the epilogue; the text after the last message part (after the last real
           attachment).  The epilogue is stored in a BODY object, and its encoding is taken from
           the general multipart header.

       $obj->file()
           See "Access to the payload" in Mail::Message::Body

       $obj->lines()
           See "Access to the payload" in Mail::Message::Body

       $obj->part(INDEX)
           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;

       $obj->parts(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])
           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.

           example:

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

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

       $obj->preamble()
           Returns the preamble; the text before the first message part (before the first real
           attachment).  The preamble is stored in a BODY object, and its encoding is taken from
           the multipart header.

       $obj->print([FILEHANDLE])
           See "Access to the payload" in Mail::Message::Body

       $obj->printEscapedFrom(FILEHANDLE)
           See "Access to the payload" in Mail::Message::Body

       $obj->string()
           See "Access to the payload" in Mail::Message::Body

       $obj->stripTrailingNewline()
           See "Access to the payload" in Mail::Message::Body

       $obj->write(OPTIONS)
           See "Access to the payload" in Mail::Message::Body

   Internals
       See documentation in the base class.

       $obj->addTransferEncHandler(NAME, CLASS|OBJECT)
       Mail::Message::Body::Multipart->addTransferEncHandler(NAME, CLASS|OBJECT)
           See "Internals" in Mail::Message::Body::Encode

       $obj->contentInfoFrom(HEAD)
           See "Internals" in Mail::Message::Body

       $obj->contentInfoTo(HEAD)
           See "Internals" in Mail::Message::Body

       $obj->fileLocation([BEGIN,END])
           See "Internals" in Mail::Message::Body

       $obj->getTransferEncHandler(TYPE)
           See "Internals" in Mail::Message::Body::Encode

       $obj->isModified()
           See "Internals" in Mail::Message::Body

       $obj->load()
           See "Internals" in Mail::Message::Body

       $obj->modified([BOOLEAN])
           See "Internals" in Mail::Message::Body

       $obj->moveLocation([DISTANCE])
           See "Internals" in Mail::Message::Body

       $obj->read(PARSER, HEAD, BODYTYPE [,CHARS [,LINES]])
           See "Internals" in Mail::Message::Body

   Error handling
       See documentation in the base class.

       $obj->AUTOLOAD()
           See "Error handling" in Mail::Message::Body

       $obj->addReport(OBJECT)
           See "Error handling" in Mail::Reporter

       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
       Mail::Message::Body::Multipart->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL,
       CALLBACK])
           See "Error handling" in Mail::Reporter

       $obj->errors()
           See "Error handling" in Mail::Reporter

       $obj->log([LEVEL [,STRINGS]])
       Mail::Message::Body::Multipart->log([LEVEL [,STRINGS]])
           See "Error handling" in Mail::Reporter

       $obj->logPriority(LEVEL)
       Mail::Message::Body::Multipart->logPriority(LEVEL)
           See "Error handling" in Mail::Reporter

       $obj->logSettings()
           See "Error handling" in Mail::Reporter

       $obj->notImplemented()
           See "Error handling" in Mail::Reporter

       $obj->report([LEVEL])
           See "Error handling" in Mail::Reporter

       $obj->reportAll([LEVEL])
           See "Error handling" in Mail::Reporter

       $obj->trace([LEVEL])
           See "Error handling" in Mail::Reporter

       $obj->warnings()
           See "Error handling" in Mail::Reporter

   Cleanup
       See documentation in the base class.

       $obj->DESTROY()
           See "Cleanup" in Mail::Reporter

DETAILS

       See documentation in the base class.

DIAGNOSTICS

       Warning: Charset $name is not known
           The encoding or decoding of a message body encounters a character set which is not
           understood by Perl's Encode module.

       Error: Data not convertible to a message (type is $type)
           An object which is not coercable into a Mail::Message::Part object was passed to the
           initiation.  The data is ignored.

       Warning: No decoder defined for transfer encoding $name.
           The data (message body) is encoded in a way which is not currently understood,
           therefore no decoding (or recoding) can take place.

       Warning: No encoder defined for transfer encoding $name.
           The data (message body) has been decoded, but the required encoding is unknown.  The
           decoded data is returned.

       Error: Package $package does not implement $method.
           Fatal error: the specific package (or one of its superclasses) does not implement this
           method where it should. This message means that some other related classes do
           implement this method however the class at hand does not.  Probably you should
           investigate this and probably inform the author of the package.

       Error: Unknown criterium $what to select parts.
           Valid choices fdr part selections are "ALL", "ACTIVE", "DELETED", "RECURSE" or a code
           reference.  However, some other argument was passed.

       Warning: Unknown line terminator $eol ignored
       Error: You cannot use foreachLine on a multipart
           foreachLine() should be used on decoded message bodies only, because it would attempt
           to modify part-headers and separators as well, which is clearly not acceptible.

SEE ALSO

       This module is part of Mail-Box distribution version 2.110, built on January 05, 2014.
       Website: http://perl.overmeer.net/mailbox/

LICENSE

       Copyrights 2001-2014 by [Mark Overmeer]. For other contributors see ChangeLog.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See http://www.perl.com/perl/misc/Artistic.html