Message::Body(3)

NAME
Mail::Message::Body - the data of a body in a message

CLASS HIERARCHY
 Mail::Message::Body + ::Construct + ::Encode
 is a Mail::Reporter

SYNOPSIS
 my Mail::Message $msg = ...;
 my $body  = $msg->body;
 my @text  = $body->lines;
 my $text  = $body->string;
 my FileHandle $file = $body->file;
 $body->print(\*FILE);

 my $content_type = $body->type;
 my $transfer_encoding = $body->transferEncoding;
 my $encoded  = $body->encode(mime_type => 'text/html',
    charset => 'us-ascii', transfer_encoding => 'NONE');
 my $decoded  = $body->decoded;

DESCRIPTION
The encoding and decoding functionality of a "Mail::Message::Body" is implemented in the "Mail::Message::Body::Encode" package. That package is automatically loaded when encoding and decoding of messages needs to take place.

The body of a message (a "Mail::Message" object) is stored in one of the body types. The functionality of each body type is equivalent, but there are performance differences. Each body type has its own documentation which contains details about its implementation.

A body can be contained in a message, but may also live without a message. In both cases it stores data, and the same questions can be asked: what type of data it is, how many bytes and lines, what encoding is used. Any body can be encoded and decoded, returning a new body object. However, bodies which are part of a message will always be in a shape that they can be written to a file or send to somewhere: they will be encoded if needed.

For example:

 my $body    = Mail::Message::Body::String->new(mime_type => 'image/gif');
 $body->print(\*OUT);    # this is binary image data...

 my $encoded = $message->body($body);
 $encoded->print(\*OUT); # ascii data, encoded image

Now encoded refers to the body of the $message which is the content of $body in a shape that it can be transmitted. Usually "base64" encoding is used.

* "Mail::Message::Body::Lines"
    Each line of the message body is stored as single scalar. This is a useful representation for a detailed look in the message body, which is usually line-organized.

* "Mail::Message::Body::String"
    The whole message body is stored in one scalar. Small messages can be contained this way without performance penalties.

* "Mail::Message::Body::File"
    The message body is stored in an external temporary file. This type of storage is especially useful when the body is large, the total folder is large, or memory is limited.

* "Mail::Message::Body::Delayed"
    The message-body is not yet read, but the exact location of the body is known so the message can be read when needed.

* "Mail::Message::Body::Multipart"
    The message body contains a set of sub-messages (which can contain multipart bodies themselves). Each sub-message is an instance of "Mail::Message::Part", which is an extension of "Mail::Message".

* "Mail::Message::Body::Nested"
    Nested messages, like "message/rfc822": they contain a message in the body. For most code, they simply behave like multiparts.

* "Mail::Message::Body::InFolder"
    NOT IMPLEMENTED YET. The message is kept in the folder, and is only taken out when the content is changed.

* "Mail::Message::Body::External"
    NOT IMPLEMENTED YET. The message is kept in a separate file, usually because the message body is large. The difference with the "::External" object is that this external storage stays this way between closing and opening of a folder. The "::External" object only uses a file when the folder is open.

Each body type has methods to produce the storage of the other types. As example, you can ask any body type for the message as a list of lines, but this call will be most efficient for the "::Body::Lines" type.

METHOD INDEX
Methods prefixed with an abbreviation are described in Mail::Reporter (MR), Mail::Message::Body::Construct (MMBC), Mail::Message::Body::Encode (MMBE).

The general methods for "Mail::Message::Body" objects:

 MMBC attach MESSAGES, OPTIONS             lines
      charset                           MR log [LEVEL [,STRINGS]]
 MMBE check                                message [MESSAGE]
      checked [BOOLEAN]                    mimeType
 MMBC concatenate COMPONENTS               modified [BOOL]
      decoded OPTIONS                      new OPTIONS
      disposition [STRING|FIELD]           nrLines
 MMBE encode OPTIONS                       print [FILE]
 MMBE encoded                              reply OPTIONS
      eol ['CR'|'LF'|'CRLF'|'NATI...    MR report [LEVEL]
   MR errors                            MR reportAll [LEVEL]
      file                                 size
 MMBC foreachLine CODE                     string
 MMBE isBinary                        MMBC stripSignature OPTIONS
      isDelayed                         MR trace [LEVEL]
      isMultipart                          transferEncoding [STRING|FI...
      isNested                             type
 MMBE isText                            MR warnings

The extra methods for extension writers:

   MR AUTOLOAD                             load
   MR DESTROY                           MR logPriority LEVEL
 MMBE addTransferEncHandler NAME,...    MR logSettings
      clone                                moveLocation [DISTANCE]
      fileLocation [BEGIN,END]          MR notImplemented
 MMBE getTransferEncHandler TYPE           read PARSER, HEAD, BODYTYPE...
   MR inGlobalDestruction             MMBE unify BODY

METHODS

new OPTIONS
     OPTION            DESCRIBED IN          DEFAULT
     based_on          Mail::Message::Body   undef
     charset           Mail::Message::Body   'us-ascii'
     checked           Mail::Message::Body   0
     eol               Mail::Message::Body   'NATIVE'
     data              Mail::Message::Body   undef
     disposition       Mail::Message::Body   undef
     file              Mail::Message::Body   undef
     log               Mail::Reporter        'WARNINGS'
     message           Mail::Message::Body   undef
     mime_type         Mail::Message::Body   'text/plain'
     modified          Mail::Message::Body   0
     trace             Mail::Reporter        'WARNINGS'
     transfer_encoding Mail::Message::Body   'NONE'

    * based_on => BODY
        The information about encodings must be taken from the specified BODY, unless specified differently.

    * charset => STRING
        Defines the character-set which is used in the data. Only useful in conbination with a "mime_type" which refers to "text" in any shape. This field is case-insensitive.

    * checked => BOOLEAN
        Whether the added information has been check not to contain illegal octets with respect to the transfer encoding and mime type. If not checked, and then set as body for a message, it will be.

    * data => ARRAY-OF-LINES | STRING
        The content of the body. The only way to set the content of a body is during the creation of the body. So if you want to modify the content of a message, you need to create a new body with the new content and add that to the body. The reason behind this, is that correct encodings and body information must be guaranteed. It avoids your hassle in calculating the number of lines in the body, and checking whether bad characters are enclosed in text.

        Specify a reference to an ARRAY of lines, each terminated by a newline. Or one STRING which may contain multiple lines, seperated and terminated by a newline.

    * disposition => STRING|FIELD
        How this message can be decomposed. The data relates to the "Content-Disposition" field. Specify a STRING which will become the field content, or a real FIELD.

        The content of this field is specified in RFC 1806. The body of the field can be "inline", to indicate that the body is intended to be displayed automatically upon display of the message. Use "attachment" to indicate that they are separate from the main body of the mail message, and that their display should not be automatic, but contingent upon some further action of the user.

        The "filename" attribute specifies a name to which is suggested to the reader of the message when it is extacted.

    * eol => 'CR'|'LF'|'CRLF'|'NATIVE'
        Convert the message into having the specified string as line terminator for all lines in the body. "NATIVE" is used to represent the "\n" on the current platform and will be translated in the applicable one.

        BE WARNED that folders with a non-native encoding may appear on your platform, for instance in Windows folders handled from a UNIX system. The eol encoding has effect on the size of the body!

    * file => FILENAME|FILEHANDLE|IOHANDLE
        Read the data from the specified file, file handle, or object of type "IO::Handle".

    * message => MESSAGE
        The message where this body belongs to.

    * mime_type => STRING|FIELD|MIME
        The type of data which is added. You may specify a content of a header line as STRING, or a FIELD object. You may also specify a MIME::Type object. In any case, it will be kept internally as a real field (a "Mail::Message::Field" object). This relates to the "Content-Type" header field.

        A mime-type specification consists of two parts: a general class ("text", "image", "application", etc) and a specific sub-class. Examples for specific classes with "text" are "plain", "html", and "xml". This field is case-insensitive but case preserving. The default mime-type is "text/plain",

    * transfer_encoding => STRING|FIELD
        The encoding that the data has. If the data is to be encoded, than you will have to call "encode()" after the body is created. That will return a new encoded body. This field is case-insensitive and relates to the "Content-Transfer-Encoding" field in the header.

    BE WARNED that, what you specify here are encodings and such which are already in place. The options will not trigger conversions. When you need conversions, first create a body with options which tell what you've got, and then call "encode" for what you need.

    Examples:

     my $body = Mail::Message::Body::String->new(file => \*IN,
        mime_type => 'text/html; charset="ISO-8859-1"');

     my $body = Mail::Message::Body::Lines->new(data => ['first', $second],
        charset => 'ISO-10646', transfer_encoding => 'NONE');

     my $body = Mail::Message::Body::Lines->new(data => \@lines,
        transfer_encoding => 'base64');

     my $body = Mail::Message::Body::Lines->new(file => 'picture.gif',
        mime_type => 'image/gif');

type
    Returns the type of information the body contains. The type is taken from the header field "Content-Type", but may have changed during encoding --or decoding-- of the body (see the "encode" method).

    The returned is a reference to a "Mail::Message::Field" object, where you can ask for the "body" (main content of the field) and the comment (after a semicolon). A field stringifies as its body only.

    Example:

     my $msg     = $folder->message(6);
     $msg->get('Content-Type')->print;
        # --> Content-Type: text/plain; charset="us-ascii"

     my $content = $msg->decoded;
     my $type    = $content->type;

     print "This is a $type message";
        # --> This is a text/plain message

     print "Comment: ", $content->comment;
        # --> Comment: charset="us-ascii"

mimeType
    Returns a "MIME::Type" object which is related to this body's type. This differs from the "type" method, which results in a "Mail::Message::Field".

charset
    Returns the character set which is used in the text body as string. This is part of the result of what the "type" method returns.

transferEncoding [STRING|FIELD]
    Returns the transfer-encoding of the data within this body. If it needs to be changed, call the "encode" or "decoded" method.

    The optional STRING or FIELD enforces a new encoding to be set, without the actual required translations.

    Example:

     my $transfer = $msg->decoded->transferEncoding;
     $transfer->print;
        # --> Content-Encoding: base64

disposition [STRING|FIELD]
    Returns (optionally after setting) how the message can be disposed (unpacked). The argument can be a STRING (which is converted into a field), or a fully prepared header field. The related header field is "Content-Disposition".

checked [BOOLEAN]
    Returns whether the body encoding has been checked or not (optionally after setting the flag to a new value).

eol ['CR'|'LF'|'CRLF'|'NATIVE']
    Returns the character (or characters) which are used to separate lines within this body.

message [MESSAGE]
    Returns the message where this body belongs to, optionally setting it to a new MESSAGE first. If "undef" is passed, the body will be disconnected from the message.

string
    Return the content of the body as a scalar (a single string). This is a copy of the internally kept information.

    Examples:

        my $text = $body->string;
        print "Body: $body\n";     # by overloading

lines
    Return the content of the body as a list of lines (in LIST context) or a reference to an array of lines (in SCALAR context). In scalar context the array of lines is cached to avoid needless copying and therefore provide much faster access for large messages.

    To just get the number of lines in the body, use the "nrLines" method, which is usually much more efficient.

    BE WARNED: For some types of bodies the reference will refer to the original data. You must not change the referenced data! If you do some of the internal values maintained by the "Mail::Message::Body" may not be updated. Use the "data()" method instead.

    Examples:

     my @lines    = $body->lines;     # copies lines
     my $line3    = ($body->lines)[3] # only one copy
     print $lines[0];

     my $linesref = $body->lines;     # reference to originals
     my $line3    = $body->lines->[3] # only one copy (faster)
     print $linesref->[0];

     print $body->[0];                # by overloading

file
    Return the content of the body as a file handle. The returned stream may be a real file, or a simulated file in any form that Perl supports. While you may not be able to write to the file handle, you can read from it.

    WARNING: Even if the file handle supports writing, do not write to the file handle. If you do some of the internal values maintained by the "Mail::Message::Body" may not be updated. Use only the "data()" method instead.

modified [BOOL]
    Returns whether the body is flagged as being modified, optionally after setting it to BOOL.

nrLines
    Returns the number of lines in the message body. For multi-part messages, this includes the header lines and boundaries of all the parts.

size
    The estimate total number of bytes in the message body. Message bodies are always simple ASCII. The decoded message, however, may contain UTF8 characters. See the "decode()" method of "Mail::Message".

print [FILE]
    Print the body to the specified file (defaults to the selected handle)

reply OPTIONS
    Create a basic reply message to the content of this body. See "Mail::Message::Construct::reply()" for details and the OPTIONS.

isDelayed
    Returns a true or false value, depending on whether the body of this message has been read from file. This can only false for a "Mail::Message::Body::Delayed".

isMultipart
    Returns whether this message-body contains parts which are messages by themselves.

isNested
    Only true for a message body which contains exactly one sub-message: the "::Nested" body type.

decoded OPTIONS
    Returns a body --an object which is (a sub-)class of a "Mail::Message::Body"-- which contains a simplified representation of textual data. The returned object may be the object where this is called on, but may also be a new body of any type.

     my $dec = $body->decoded;

    is equivalent with

     my $dec = $body->encode(mime_type => 'text/plain', charset => 'us-ascii',
        transfer_encoding => 'NONE');

    The $dec which is returned is a body. Ask with the "mimeType" method what is produced. This body is not related to a header, so you can not ask "$dec->get('Content-Type')"!

     OPTION      DESCRIBED IN            DEFAULT
     result_type Mail::Message::Body     <same as current>

METHODS for extension writers

read PARSER, HEAD, BODYTYPE [,CHARS [,LINES]]
    Read the body with the PARSER from file. The implementation of this method will differ between types of bodies. The BODYTYPE argument is a class name or a code reference of a routine which can produce a class name, and is used in multipart bodies to determine the type of the body for each part.

    The CHARS argument is the estimated number of bytes in the body, or "undef" when this is not known. This data can sometimes be derived from the header (the "Content-Length" line) or file-size.

    The second argument is the estimated number of LINES of the body. It is less useful than the CHARS but may be of help determining whether the message separator is trustworthy. This value may be found in the "Lines" field of the header.

clone
    Return a copy of this body, usually to be included in a cloned message (see "Mail::Message::clone").

fileLocation [BEGIN,END]
    The location of the body in the file. Returned a list containing begin and end. The begin is the offsets of the first byte if the folder used for this body. The end is the offset of the first byte of the next message.

moveLocation [DISTANCE]
    Move the registration of the message to a new location over DISTANCE. This is called when the message is written to a new version of the same folder-file.

load
    Be sure that the body is loaded. This returns the loaded body.

SEE ALSO
Mail::Box-Overview

For support and additional documentation, see http://perl.overmeer.net/mailbox/

AUTHOR
Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION
This code is beta, version 2.018.

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.