| Mail::Message::Body(3pm) | User Contributed Perl Documentation | Mail::Message::Body(3pm) |
Mail::Message::Body - the data of a body in a message
Mail::Message::Body has extra code in Mail::Message::Body::Construct Mail::Message::Body::Encode 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
my Mail::Message $msg = ...;
my $body = $msg->body;
my @text = $body->lines;
my $text = $body->string;
my $file = $body->file; # IO::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;
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.
Extends "DESCRIPTION" in Mail::Reporter.
example: stringification of body
print $msg->body; # implicit by print
my $body = $msg->body;
my $x = "$body"; # explicit by interpolation
example: use of numeric comparison on a body
my $skip = $folder->message(3);
foreach my $msg (@$folder)
{ next if $msg == $skip;
$msg->send;
}
example: using a body as array
print $body->lines->[1]; # second line
print $body->[1]; # same
my @lines = $body->lines;
my @lines = @$body; # same
Extends "METHODS" in Mail::Reporter.
Extends "Constructors" in Mail::Reporter.
-Option --Defined in --Default
based_on undef
charset 'PERL'
checked <false>
content_id undef
data undef
description undef
disposition undef
eol 'NATIVE'
file undef
filename undef
log Mail::Reporter 'WARNINGS'
message undef
mime_type 'text/plain'
modified <false>
trace Mail::Reporter 'WARNINGS'
transfer_encoding 'none'
When a known CHARSET is provided and the mime-type says "text", then the data is expected to be raw octets in that particular encoding (see Encode). When 'PERL' is given, then then the data is in Perl's internal encoding; either cp1252 or utf8. More details in "Character encoding PERL"
A "Content-ID" is supposed to be globally unique. As such, it is common to append '@computer.domain' to the end of some unique string. As other content in the multipart/related container also needs to know what this "Content-ID" is, this should be left to the imagination of the person making the content (for now).
As a MIME header field, the "Content-ID" string is expected to be inside angle brackets
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.
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.
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!
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",
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', content_id => '<12345@example.com>',
disposition => 'inline');
my $dec = $body->decoded;
is equivalent with
my $dec = $body->encode
( mime_type => 'text/plain'
, transfer_encoding => 'none'
, charset => 'PERL'
);
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 --Default
result_type <same as current>
example:
my $body = $msg->decoded->eol('NATIVE');
my $char = $msg->decoded->eol;
The argument can be a STRING (which is converted into a field), or a fully prepared header $field.
The argument can be a STRING (which is converted into a field), or a fully prepared header field.
The argument can be a STRING (which is converted into a field), or a fully prepared header field.
example:
if($body->mimeType eq 'text/html') {...}
print $body->mimeType->simplified;
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') {...}
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"
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.
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
example:
my $text = $body->string;
print "Body: $body\n"; # by overloading
-Option --Default
filename <required>
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";
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().
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.
Extends "Error handling" in Mail::Reporter.
Extends "Cleanup" in Mail::Reporter.
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.
The body of a message can be stored in many ways. Roughly, 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
The whole message body is stored in one scalar. Small messages can be contained this way without performance penalties.
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.
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.
NOT IMPLEMENTED YET. The message is kept in the folder, and is only taken out when the content is changed.
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.
Complex bodies
The message-body is not yet read, but the exact location of the body is known so the message can be read when needed. This is part of the lazy extraction mechanism. Once extracted, the object can become any simple or complex body.
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.
Nested messages, like "message/rfc822": they contain a message in the body. For most code, they simply behave like multiparts.
A body object can be part of a message, or stand-alone. In case it is a part of a message, the "transport encoding" and the content must be in a shape that the data can be transported via SMTP.
However, when you want to process the body data in simple Perl (or when you construct the body data from normal Perl strings), you need to be aware of Perl's internal representation of strings. That can either be cp1252 (extended latin1) or utf8 (not real UTF-8, but something alike, see the perlunicode manual page) So, before you start using the data from an incoming message, do
my $body = $msg->decoded;
my @lines = $body->lines;
Now, the body has character-set 'PERL' (when it is text)
When you create a new body which contains text content (the default), it will be created with character-set 'PERL' unless you specify a character-set explicitly.
my $body = Mail::Box::Body::Lines->new(data => \@lines); # now mime=text/plain, charset=PERL my $msg = Mail::Message->buildFromBody($body); $msg->body($body); $msg->attach($body); # etc # these all will convert the charset=PERL into real utf-8, # cp1252 or us-ascii, which depends on the characters found.
Autodetection of character-set
This "Body" object represents data as part of an existing message, or to become part of a message. The body can be in two states:
In the first case, the body content has no transfer encoding on it ("none"), and the character-set is "PERL". In the second version, the body may have transfer encoding and has an (IANA listed) charset on it (defaults to "us-ascii")
Using encode() (maybe via Mail::Message::Body subroutine decode), you can convert bodies from one state into a different one. In one go, you can change the transfer-encoding, the character-set, or whether it is in PERL string format or raw (in bytes).
[3.013] A serious problem is created when a conversion is needed, while the input or output character-set is not explicitly known. The email RFCs state that the default is "us-ascii". However, in the real world it can be anything. Therefore, in such situations autodetection kicks in.
This module is part of Mail-Message distribution version 3.015, built on December 11, 2023. Website: http://perl.overmeer.net/CPAN/
Copyrights 2001-2023 by [Mark Overmeer <markov@cpan.org>]. 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://dev.perl.org/licenses/
| 2023-12-11 | perl v5.36.0 |