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

NAME

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

INHERITANCE

 Mail::Message::Body has extra code in
   Mail::Message::Body::Encode
   Mail::Message::Body::Construct
 Mail::Message::Body
   is a Mail::Reporter
 Mail::Message::Body is extended by
   Mail::Message::Body::File
   Mail::Message::Body::Lines
   Mail::Message::Body::Multipart
   Mail::Message::Body::Nested
   Mail::Message::Body::String
 Mail::Message::Body is realized by
   Mail::Message::Body::Delayed

SYNOPSIS

 my Mail::Message $msg = ...;
 my $body  = $msg->body;
 my @text  = $body->lines;
 my $text  = $body->string;
 my IO::Handle $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');\n";
 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. Methods to simply build an process body objects are implemented in Mail::Message::Body::Construct.

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

OVERLOADED

overload: ``''

(stringification) Returns the body as string --which will trigger completion-- unless called to produce a string for Carp. The latter to avoid deep recursions.

Example: stringification of body

 print $msg->body;   # implicit by print
 my $body = $msg->body;
 my $x    = "$body"; # explicit by interpolation

overload: '==' and '!='

(numeric comparison) compares if two references point to the same message. This only produces correct results is both arguments are message references within the same folder.

Example: use of numeric comparison on a body

 my $skip = $folder->message(3);
 foreach my $msg (@$folder)
 {   next if $msg == $skip;
     $msg->send;
 }

overload: @{}

When a body object is used as being an array reference, the lines of the body are returned. This is the same as using lines().

Example: using a body as array

 print $body->lines->[1];  # second line
 print $body->[1];         # same
 my @lines = $body->lines;
 my @lines = @$body;       # same

overload: bool

Always returns a true value, which is needed to have overloaded objects to be used as in if($body). Otherwise, if(defined $body) would be needed to avoid a runtime error.

METHODS

Constructors

$obj->clone

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

Mail::Message::Body->new(OPTIONS)

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.

 Option             Defined in       Default        
 based_on                            undef          
 charset                             C<'us-ascii'>  
 checked                             <false>        
 data                                undef          
 disposition                         undef          
 eol                                 C<'NATIVE'>    
 file                                undef          
 log                L<Mail::Reporter>  C<'WARNINGS'>  
 message                             undef          
 mime_type                           C<'text/plain'>
 modified                            <false>        
 trace              L<Mail::Reporter>  C<'WARNINGS'>  
 transfer_encoding                   C<'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 combination 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, separated 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 extracted.

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

. log LEVEL

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

. modified BOOLEAN

Whether the body is flagged modified, directly from its creation.

. trace LEVEL

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

Example:

 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');

Constructing a body

$obj->attach(MESSAGES, OPTIONS)

See Constructing a body in the Mail::Message::Body::Construct manpage

$obj->check

See Constructing a body in the Mail::Message::Body::Encode manpage

$obj->concatenate(COMPONENTS)

See Constructing a body in the Mail::Message::Body::Construct manpage

$obj->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 $dec body is not related to a header.

 Option       Defined in  Default          
 result_type              <same as current>

. result_type CLASS

$obj->encode(OPTIONS)

See Constructing a body in the Mail::Message::Body::Encode manpage

$obj->encoded

See Constructing a body in the Mail::Message::Body::Encode manpage

$obj->eol(['CR'|'LF'|'CRLF'|'NATIVE'])

Returns the character (or characters) which are used to separate lines within this body. When a kind of separator is specified, the body is translated to contain the specified line endings.

$obj->foreachLine(CODE)

See Constructing a body in the Mail::Message::Body::Construct manpage

$obj->stripSignature(OPTIONS)

See Constructing a body in the Mail::Message::Body::Construct manpage

$obj->unify(BODY)

See Constructing a body in the Mail::Message::Body::Encode manpage

The body

$obj->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.

$obj->isMultipart

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

$obj->isNested

Only true for a message body which contains exactly one sub-message: the Mail::Message::Body::Nested body type.

$obj->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.

About the payload

$obj->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.

$obj->checked([BOOLEAN])

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

$obj->disposition([STRING|FIELD])

Returns (optionally after setting) how the message can be disposed (unpacked). The related header field is Content-Disposition. A Mail::Message::Field object is returned (which stringifies into the field content). The field content will be none if no disposition was specified.

The argument can be a STRING (which is converted into a field), or a fully prepared header field.

$obj->dispositionFilename([DIRECTORY])

See About the payload in the Mail::Message::Body::Encode manpage

$obj->isBinary

See About the payload in the Mail::Message::Body::Encode manpage

$obj->isText

See About the payload in the Mail::Message::Body::Encode manpage

$obj->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.

Example:

 if($body->mimeType eq 'text/html') {...}
 print $body->mimeType->simplified;

$obj->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.

$obj->size

The total number of bytes in the message body. The size of the body is computed in the shape it is in. For example, if this is a base64 encoded message, the size of the encoded data is returned; you may want to call Mail::Message::decoded() first.

$obj->transferEncoding([STRING|FIELD])

Returns the transfer-encoding of the data within this body as Mail::Message::Field (which stringifies to its content). If it needs to be changed, call the encode() or decoded() method. When no encoding is present, the field contains the text none.

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
 print $transfer;    # --> base64
 if($msg->body->transferEncoding eq 'none') {...}

$obj->type([STRING|FIELD])

Returns the type of information the body contains as Mail::Message::Field object. The type is taken from the header field Content-Type. If the header did not contain that field, then you will get a default field containing text/plain.

You usually can better use mimeType(), because that will return a clever object with type information.

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\n";
    # --> This is a text/plain; charset="us-ascii" message
 print "This is a ", $type->body, "message\n";
    # --> This is a text/plain message
 print "Comment: ", $type->comment, "\n";
    # --> Comment: charset="us-ascii"

Access to the payload

$obj->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 of the Mail::Message::Body may not be updated.

$obj->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 essential internal variables of the Mail::Message::Body may not be updated.

Example:

 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

$obj->print([FILEHANDLE])

Print the body to the specified FILEHANDLE (defaults to the selected handle). The handle may be a GLOB, an IO::File object, or... any object with a print() method will do. Nothing useful is returned.

$obj->printEscapedFrom(FILEHANDLE)

Print the body to the specified FILEHANDLE but all lines which start with 'From ' (optionally already preceded by >'s) will habe an > added in front. Nothing useful is returned.

$obj->string

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

Example:

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

$obj->write(OPTIONS)

Write the content of the body to a file. Be warned that you may want to decode the body before writing it!

 Option    Defined in  Default   
 filename              <required>

. filename FILENAME

Example: write the data to a file

 use File::Temp;
 my $fn = tempfile;
 $message->decoded->write(filename => $fn)
    or die "Couldn't write to $fn: $!\n";

Example: using the content-disposition information to write

 use File::Temp;
 my $dir = tempdir; mkdir $dir or die;
 my $fn  = $message->body->dispositionFilename($dir);
 $message->decoded->write(filename => $fn)
    or die "Couldn't write to $fn: $!\n";

Internals

$obj->addTransferEncHandler(NAME, CLASS|OBJECT)

Mail::Message::Body->addTransferEncHandler(NAME, CLASS|OBJECT)

See Internals in the Mail::Message::Body::Encode manpage

$obj->contentInfoFrom(HEAD)

Transfer the body related info from the header into this body.

$obj->contentInfoTo(HEAD)

Copy the content information (the Content-* fields) into the specified HEAD. The body was created from raw data without the required information, which must be added. See also contentInfoFrom().

$obj->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.

$obj->getTransferEncHandler(TYPE)

See Internals in the Mail::Message::Body::Encode manpage

$obj->isModified

Returns whether the body has changed.

$obj->load

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

$obj->modified([BOOLEAN])

Change the body modification flag. This will force a re-write of the body to a folder file when it is closed. It is quite dangerous to change the body: the same body may be shared between messages within your program.

Especially be warned that you have to change the message-id when you change the body of the message: no two messages should have the same id.

Without value, the current setting is returned, although you can better use isModified().

$obj->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.

$obj->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.

Error handling

$obj->AUTOLOAD

When an unknown method is called on a message body object, this may not be problematic. For performance reasons, some methods are implemented in separate files, and only demand-loaded. If this delayed compilation of additional modules does not help, an error will be produced.

$obj->addReport(OBJECT)

See Error handling in the Mail::Reporter manpage

$obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

Mail::Message::Body->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

See Error handling in the Mail::Reporter manpage

$obj->errors

See Error handling in the Mail::Reporter manpage

$obj->log([LEVEL [,STRINGS]])

Mail::Message::Body->log([LEVEL [,STRINGS]])

See Error handling in the Mail::Reporter manpage

$obj->logPriority(LEVEL)

Mail::Message::Body->logPriority(LEVEL)

See Error handling in the Mail::Reporter manpage

$obj->logSettings

See Error handling in the Mail::Reporter manpage

$obj->notImplemented

See Error handling in the Mail::Reporter manpage

$obj->report([LEVEL])

See Error handling in the Mail::Reporter manpage

$obj->reportAll([LEVEL])

See Error handling in the Mail::Reporter manpage

$obj->trace([LEVEL])

See Error handling in the Mail::Reporter manpage

$obj->warnings

See Error handling in the Mail::Reporter manpage

Cleanup

$obj->DESTROY

See Cleanup in the Mail::Reporter manpage

$obj->inGlobalDestruction

See Cleanup in the Mail::Reporter manpage

DIAGNOSTICS

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.

DETAILS

Access to the body

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.

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.

Body class implementation

The body of a message can be stored in many ways. Roughtly, the implementations can be split in two groups: the data collectors and the complex bodies. The primer implement various ways to access data, and are full compatible: they only differ in performance and memory footprint under different circumstances. The latter are created to handle complex multiparts and lazy extraction.

Data collector bodies

Complex bodies

REFERENCES

See the MailBox website at http://perl.overmeer.net/mailbox/ for more details.

COPYRIGHTS

Distribution version 2.059. Written by Mark Overmeer (mark@overmeer.net) See the ChangeLog for other contributors.

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

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