1Mail::Message::Body(3)User Contributed Perl DocumentationMail::Message::Body(3)
2
6 Mail::Message::Body - the data of a body in a message
7
9 Mail::Message::Body has extra code in
10 Mail::Message::Body::Construct
11 Mail::Message::Body::Encode
12 Mail::Message::Body
14 is a Mail::Reporter
15 Mail::Message::Body is extended by
17 Mail::Message::Body::File
18 Mail::Message::Body::Lines
19 Mail::Message::Body::Multipart
20 Mail::Message::Body::Nested
21 Mail::Message::Body::String
22 Mail::Message::Body is realized by
24 Mail::Message::Body::Delayed
25
27 my Mail::Message $msg = ...;
28 my $body = $msg->body;
29 my @text = $body->lines;
30 my $text = $body->string;
31 my $file = $body->file; # IO::File
32 $body->print(\*FILE);
33 my $content_type = $body->type;
35 my $transfer_encoding = $body->transferEncoding;
36 my $encoded = $body->encode(mime_type => 'text/html',
37 charset => 'us-ascii', transfer_encoding => 'none');\n";
38 my $decoded = $body->decoded;
39
41 The encoding and decoding functionality of a Mail::Message::Body is
42 implemented in the Mail::Message::Body::Encode package. That package
43 is automatically loaded when encoding and decoding of messages needs to
44 take place. Methods to simply build an process body objects are
45 implemented in Mail::Message::Body::Construct.
46 The body of a message (a Mail::Message object) is stored in one of the
48 many body types. The functionality of each body type is equivalent,
49 but there are performance differences. Each body type has its own
50 documentation with details about its implementation.
51
53 overload: ""
54 (stringification) Returns the body as string --which will trigger
55 completion-- unless called to produce a string for "Carp". The
56 latter to avoid deep recursions.
57 example: stringification of body
59 print $msg->body; # implicit by print
61 my $body = $msg->body;
63 my $x = "$body"; # explicit by interpolation
64 overload: '==' and '!='
66 (numeric comparison) compares if two references point to the same
67 message. This only produces correct results is both arguments are
68 message references within the same folder.
69 example: use of numeric comparison on a body
71 my $skip = $folder->message(3);
73 foreach my $msg (@$folder)
74 { next if $msg == $skip;
75 $msg->send;
76 }
77 overload: @{}
79 When a body object is used as being an array reference, the lines
80 of the body are returned. This is the same as using lines().
81 example: using a body as array
83 print $body->lines->[1]; # second line
85 print $body->[1]; # same
86 my @lines = $body->lines;
88 my @lines = @$body; # same
89 overload: bool
91 Always returns a true value, which is needed to have overloaded
92 objects to be used as in "if($body)". Otherwise, "if(defined
93 $body)" would be needed to avoid a runtime error.
94
96 Constructors
97 $obj->clone
98 Return a copy of this body, usually to be included in a cloned
99 message. Use Mail::Message::clone() for a whole message.
100 Mail::Message::Body->new(OPTIONS)
102 BE WARNED that, what you specify here are encodings and such which
103 are already in place. The options will not trigger conversions.
104 When you need conversions, first create a body with options which
105 tell what you've got, and then call encode() for what you need.
106 -Option --Defined in --Default
108 based_on undef
109 charset 'PERL' or <undef>
110 checked <false>
111 data undef
112 description undef
113 disposition undef
114 eol 'NATIVE'
115 file undef
116 log Mail::Reporter 'WARNINGS'
117 message undef
118 mime_type 'text/plain'
119 modified <false>
120 trace Mail::Reporter 'WARNINGS'
121 transfer_encoding 'none'
122 based_on => BODY
124 The information about encodings must be taken from the specified
125 BODY, unless specified differently.
126 charset => CHARSET|'PERL'
128 Defines the character-set which is used in the data. Only useful
129 in combination with a "mime_type" which refers to "text" in any
130 shape, which does not contain an explicit charset already. This
131 field is case-insensitive.
132 When a known CHARSET is provided and the mime type says "text",
134 then the data is expected to be bytes in that particular encoding
135 (see Encode). When 'PERL' is given, then then the data is in
136 Perl's internal encoding (either latin1 or utf8, you shouldn't
137 know!) More details in "Character encoding PERL"
138 checked => BOOLEAN
140 Whether the added information has been check not to contain
141 illegal octets with respect to the transfer encoding and mime
142 type. If not checked, and then set as body for a message, it
143 will be.
144 data => ARRAY-OF-LINES | STRING
146 The content of the body. The only way to set the content of a
147 body is during the creation of the body. So if you want to
148 modify the content of a message, you need to create a new body
149 with the new content and add that to the body. The reason behind
150 this, is that correct encodings and body information must be
151 guaranteed. It avoids your hassle in calculating the number of
152 lines in the body, and checking whether bad characters are
153 enclosed in text.
154 Specify a reference to an ARRAY of lines, each terminated by a
156 newline. Or one STRING which may contain multiple lines,
157 separated and terminated by a newline.
158 description => STRING|FIELD
160 Informal information about the body content. The data relates to
161 the "Content-Description" field. Specify a STRING which will
162 become the field content, or a real FIELD.
163 disposition => STRING|FIELD
165 How this message can be decomposed. The data relates to the
166 "Content-Disposition" field. Specify a STRING which will become
167 the field content, or a real FIELD.
168 The content of this field is specified in RFC 1806. The body of
170 the field can be "inline", to indicate that the body is intended
171 to be displayed automatically upon display of the message. Use
172 "attachment" to indicate that they are separate from the main
173 body of the mail message, and that their display should not be
174 automatic, but contingent upon some further action of the user.
175 The "filename" attribute specifies a name to which is suggested
177 to the reader of the message when it is extracted.
178 eol => 'CR'|'LF'|'CRLF'|'NATIVE'
180 Convert the message into having the specified string as line
181 terminator for all lines in the body. "NATIVE" is used to
182 represent the "\n" on the current platform and will be translated
183 in the applicable one.
184 BE WARNED that folders with a non-native encoding may appear on
186 your platform, for instance in Windows folders handled from a
187 UNIX system. The eol encoding has effect on the size of the
188 body!
189 file => FILENAME|FILEHANDLE|IOHANDLE
191 Read the data from the specified file, file handle, or object of
192 type "IO::Handle".
193 log => LEVEL
195 message => MESSAGE
196 The message where this body belongs to.
197 mime_type => STRING|FIELD|MIME
199 The type of data which is added. You may specify a content of a
200 header line as STRING, or a FIELD object. You may also specify a
201 MIME::Type object. In any case, it will be kept internally as a
202 real field (a Mail::Message::Field object). This relates to the
203 "Content-Type" header field.
204 A mime-type specification consists of two parts: a general class
206 ("text", "image", "application", etc) and a specific sub-class.
207 Examples for specific classes with "text" are "plain", "html",
208 and "xml". This field is case-insensitive but case preserving.
209 The default mime-type is "text/plain",
210 modified => BOOLEAN
212 Whether the body is flagged modified, directly from its creation.
213 trace => LEVEL
215 transfer_encoding => STRING|FIELD
216 The encoding that the data has. If the data is to be encoded,
217 than you will have to call encode() after the body is created.
218 That will return a new encoded body. This field is case-
219 insensitive and relates to the "Content-Transfer-Encoding" field
220 in the header.
221 example:
223 my $body = Mail::Message::Body::String->new(file => \*IN,
225 mime_type => 'text/html; charset="ISO-8859-1"');
226 my $body = Mail::Message::Body::Lines->new(data => ['first', $second],
228 charset => 'ISO-10646', transfer_encoding => 'none');
229 my $body = Mail::Message::Body::Lines->new(data => \@lines,
231 transfer_encoding => 'base64');
232 my $body = Mail::Message::Body::Lines->new(file => 'picture.gif',
234 mime_type => 'image/gif');
235 Constructing a body
237 $obj->attach(MESSAGES, OPTIONS)
238 See "Constructing a body" in Mail::Message::Body::Construct
239 $obj->check
241 See "Constructing a body" in Mail::Message::Body::Encode
242 $obj->concatenate(COMPONENTS)
244 See "Constructing a body" in Mail::Message::Body::Construct
245 $obj->decoded(OPTIONS)
247 Returns a body, an object which is (a sub-)class of a
248 Mail::Message::Body, which contains a simplified representation of
249 textual data. The returned object may be the object where this is
250 called on, but may also be a new body of any type.
251 my $dec = $body->decoded;
253 is equivalent with
255 my $dec = $body->encode
257 ( mime_type => 'text/plain'
258 , transfer_encoding => 'none'
259 , charset => 'PERL'
260 );
261 The $dec which is returned is a body. Ask with the mimeType()
263 method what is produced. This $dec body is not related to a
264 header.
265 -Option --Default
267 result_type <same as current>
268 result_type => CLASS
270 $obj->encode(OPTIONS)
271 See "Constructing a body" in Mail::Message::Body::Encode
272 $obj->encoded
274 See "Constructing a body" in Mail::Message::Body::Encode
275 $obj->eol(['CR'|'LF'|'CRLF'|'NATIVE'])
277 Returns the character (or characters) which are used to separate
278 lines within this body. When a kind of separator is specified, the
279 body is translated to contain the specified line endings.
280 example:
282 my $body = $msg->decoded->eol('NATIVE');
284 my $char = $msg->decoded->eol;
285 $obj->foreachLine(CODE)
287 See "Constructing a body" in Mail::Message::Body::Construct
288 $obj->stripSignature(OPTIONS)
290 See "Constructing a body" in Mail::Message::Body::Construct
291 $obj->unify(BODY)
293 See "Constructing a body" in Mail::Message::Body::Encode
294 The body
296 $obj->isDelayed
297 Returns a true or false value, depending on whether the body of
298 this message has been read from file. This can only false for a
299 Mail::Message::Body::Delayed.
300 $obj->isMultipart
302 Returns whether this message-body contains parts which are messages
303 by themselves.
304 $obj->isNested
306 Only true for a message body which contains exactly one sub-
307 message: the "Mail::Message::Body::Nested" body type.
308 $obj->message([MESSAGE])
310 Returns the message where this body belongs to, optionally setting
311 it to a new MESSAGE first. If "undef" is passed, the body will be
312 disconnected from the message.
313 About the payload
315 $obj->charset
316 Returns the character set which is used in the text body as string.
317 This is part of the result of what the "type" method returns.
318 $obj->checked([BOOLEAN])
320 Returns whether the body encoding has been checked or not
321 (optionally after setting the flag to a new value).
322 $obj->description([STRING|FIELD])
324 Returns (optionally after setting) the informal description of the
325 body content. The related header field is "Content-Description".
326 A Mail::Message::Field object is returned (which stringifies into
327 the field content). The field content will be "none" if no
328 disposition was specified.
329 The argument can be a STRING (which is converted into a field), or
331 a fully prepared header field.
332 $obj->disposition([STRING|FIELD])
334 Returns (optionally after setting) how the message can be disposed
335 (unpacked). The related header field is "Content-Disposition". A
336 Mail::Message::Field object is returned (which stringifies into the
337 field content). The field content will be "none" if no disposition
338 was specified.
339 The argument can be a STRING (which is converted into a field), or
341 a fully prepared header field.
342 $obj->dispositionFilename([DIRECTORY])
344 See "About the payload" in Mail::Message::Body::Encode
345 $obj->isBinary
347 See "About the payload" in Mail::Message::Body::Encode
348 $obj->isText
350 See "About the payload" in Mail::Message::Body::Encode
351 $obj->mimeType
353 Returns a MIME::Type object which is related to this body's type.
354 This differs from the "type" method, which results in a
355 Mail::Message::Field.
356 example:
358 if($body->mimeType eq 'text/html') {...}
360 print $body->mimeType->simplified;
361 $obj->nrLines
363 Returns the number of lines in the message body. For multi-part
364 messages, this includes the header lines and boundaries of all the
365 parts.
366 $obj->size
368 The total number of bytes in the message body. The size of the body
369 is computed in the shape it is in. For example, if this is a base64
370 encoded message, the size of the encoded data is returned; you may
371 want to call Mail::Message::decoded() first.
372 $obj->transferEncoding([STRING|FIELD])
374 Returns the transfer-encoding of the data within this body as
375 Mail::Message::Field (which stringifies to its content). If it
376 needs to be changed, call the encode() or decoded() method. When
377 no encoding is present, the field contains the text "none".
378 The optional STRING or FIELD enforces a new encoding to be set,
380 without the actual required translations.
381 example:
383 my $transfer = $msg->decoded->transferEncoding;
385 $transfer->print; # --> Content-Encoding: base64
386 print $transfer; # --> base64
387 if($msg->body->transferEncoding eq 'none') {...}
389 $obj->type([STRING|FIELD])
391 Returns the type of information the body contains as
392 Mail::Message::Field object. The type is taken from the header
393 field "Content-Type". If the header did not contain that field,
394 then you will get a default field containing "text/plain".
395 You usually can better use mimeType(), because that will return a
397 clever object with type information.
398 example:
400 my $msg = $folder->message(6);
402 $msg->get('Content-Type')->print;
403 # --> Content-Type: text/plain; charset="us-ascii"
404 my $content = $msg->decoded;
406 my $type = $content->type;
407 print "This is a $type message\n";
409 # --> This is a text/plain; charset="us-ascii" message
410 print "This is a ", $type->body, "message\n";
412 # --> This is a text/plain message
413 print "Comment: ", $type->comment, "\n";
415 # --> Comment: charset="us-ascii"
416 Access to the payload
418 $obj->endsOnNewline
419 Returns whether the last line of the body is terminated by a new-
420 line (in transport it will become a CRLF). An empty body will
421 return true as well: the newline comes from the line before it.
422 $obj->file
424 Return the content of the body as a file handle. The returned
425 stream may be a real file, or a simulated file in any form that
426 Perl supports. While you may not be able to write to the file
427 handle, you can read from it.
428 WARNING: Even if the file handle supports writing, do not write to
430 the file handle. If you do, some of the internal values of the
431 Mail::Message::Body may not be updated.
432 $obj->lines
434 Return the content of the body as a list of lines (in LIST context)
435 or a reference to an array of lines (in SCALAR context). In scalar
436 context the array of lines is cached to avoid needless copying and
437 therefore provide much faster access for large messages.
438 To just get the number of lines in the body, use the nrLines()
440 method, which is usually much more efficient.
441 BE WARNED: For some types of bodies the reference will refer to the
443 original data. You must not change the referenced data! If you do,
444 some of the essential internal variables of the Mail::Message::Body
445 may not be updated.
446 example:
448 my @lines = $body->lines; # copies lines
450 my $line3 = ($body->lines)[3] # only one copy
451 print $lines[0];
452 my $linesref = $body->lines; # reference to originals
454 my $line3 = $body->lines->[3] # only one copy (faster)
455 print $linesref->[0];
456 print $body->[0]; # by overloading
458 $obj->print([FILEHANDLE])
460 Print the body to the specified FILEHANDLE (defaults to the
461 selected handle). The handle may be a GLOB, an IO::File object,
462 or... any object with a "print()" method will do. Nothing useful
463 is returned.
464 $obj->printEscapedFrom(FILEHANDLE)
466 Print the body to the specified FILEHANDLE but all lines which
467 start with 'From ' (optionally already preceded by >'s) will habe
468 an > added in front. Nothing useful is returned.
469 $obj->string
471 Return the content of the body as a scalar (a single string). This
472 is a copy of the internally kept information.
473 example:
475 my $text = $body->string;
477 print "Body: $body\n"; # by overloading
478 $obj->stripTrailingNewline
480 Remove the newline from the last line, or the last line if it does
481 not contain anything else than a newline.
482 $obj->write(OPTIONS)
484 Write the content of the body to a file. Be warned that you may
485 want to decode the body before writing it!
486 -Option --Default
488 filename <required>
489 filename => FILENAME
491 example: write the data to a file
493 use File::Temp;
495 my $fn = tempfile;
496 $message->decoded->write(filename => $fn)
497 or die "Couldn't write to $fn: $!\n";
498 example: using the content-disposition information to write
500 use File::Temp;
502 my $dir = tempdir; mkdir $dir or die;
503 my $fn = $message->body->dispositionFilename($dir);
504 $message->decoded->write(filename => $fn)
505 or die "Couldn't write to $fn: $!\n";
506 Internals
508 $obj->addTransferEncHandler(NAME, CLASS|OBJECT)
509 Mail::Message::Body->addTransferEncHandler(NAME, CLASS|OBJECT)
510 See "Internals" in Mail::Message::Body::Encode
512 $obj->contentInfoFrom(HEAD)
514 Transfer the body related info from the header into this body.
515 $obj->contentInfoTo(HEAD)
517 Copy the content information (the "Content-*" fields) into the
518 specified HEAD. The body was created from raw data without the
519 required information, which must be added. See also
520 contentInfoFrom().
521 $obj->fileLocation([BEGIN,END])
523 The location of the body in the file. Returned a list containing
524 begin and end. The begin is the offsets of the first byte if the
525 folder used for this body. The end is the offset of the first byte
526 of the next message.
527 $obj->getTransferEncHandler(TYPE)
529 See "Internals" in Mail::Message::Body::Encode
530 $obj->isModified
532 Returns whether the body has changed.
533 $obj->load
535 Be sure that the body is loaded. This returns the loaded body.
536 $obj->modified([BOOLEAN])
538 Change the body modification flag. This will force a re-write of
539 the body to a folder file when it is closed. It is quite dangerous
540 to change the body: the same body may be shared between messages
541 within your program.
542 Especially be warned that you have to change the message-id when
544 you change the body of the message: no two messages should have the
545 same id.
546 Without value, the current setting is returned, although you can
548 better use isModified().
549 $obj->moveLocation([DISTANCE])
551 Move the registration of the message to a new location over
552 DISTANCE. This is called when the message is written to a new
553 version of the same folder-file.
554 $obj->read(PARSER, HEAD, BODYTYPE [,CHARS [,LINES]])
556 Read the body with the PARSER from file. The implementation of this
557 method will differ between types of bodies. The BODYTYPE argument
558 is a class name or a code reference of a routine which can produce
559 a class name, and is used in multipart bodies to determine the type
560 of the body for each part.
561 The CHARS argument is the estimated number of bytes in the body, or
563 "undef" when this is not known. This data can sometimes be derived
564 from the header (the "Content-Length" line) or file-size.
565 The second argument is the estimated number of LINES of the body.
567 It is less useful than the CHARS but may be of help determining
568 whether the message separator is trustworthy. This value may be
569 found in the "Lines" field of the header.
570 Error handling
572 $obj->AUTOLOAD
573 When an unknown method is called on a message body object, this may
574 not be problematic. For performance reasons, some methods are
575 implemented in separate files, and only demand-loaded. If this
576 delayed compilation of additional modules does not help, an error
577 will be produced.
578 $obj->addReport(OBJECT)
580 See "Error handling" in Mail::Reporter
581 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
583 Mail::Message::Body->defaultTrace([LEVEL]|[LOGLEVEL,
584 TRACELEVEL]|[LEVEL, CALLBACK])
585 See "Error handling" in Mail::Reporter
587 $obj->errors
589 See "Error handling" in Mail::Reporter
590 $obj->log([LEVEL [,STRINGS]])
592 Mail::Message::Body->log([LEVEL [,STRINGS]])
593 See "Error handling" in Mail::Reporter
595 $obj->logPriority(LEVEL)
597 Mail::Message::Body->logPriority(LEVEL)
598 See "Error handling" in Mail::Reporter
600 $obj->logSettings
602 See "Error handling" in Mail::Reporter
603 $obj->notImplemented
605 See "Error handling" in Mail::Reporter
606 $obj->report([LEVEL])
608 See "Error handling" in Mail::Reporter
609 $obj->reportAll([LEVEL])
611 See "Error handling" in Mail::Reporter
612 $obj->trace([LEVEL])
614 See "Error handling" in Mail::Reporter
615 $obj->warnings
617 See "Error handling" in Mail::Reporter
618 Cleanup
620 $obj->DESTROY
621 See "Cleanup" in Mail::Reporter
622 $obj->inGlobalDestruction
624 See "Cleanup" in Mail::Reporter
625
627 Access to the body
628 A body can be contained in a message, but may also live without a
629 message. In both cases it stores data, and the same questions can be
630 asked: what type of data it is, how many bytes and lines, what encoding
631 is used. Any body can be encoded and decoded, returning a new body
632 object. However, bodies which are part of a message will always be in
633 a shape that they can be written to a file or send to somewhere: they
634 will be encoded if needed.
635 Body class implementation
637 Data collector bodies
638 · Mail::Message::Body::String
640 The whole message body is stored in one scalar. Small messages can
642 be contained this way without performance penalties.
643 · Mail::Message::Body::Lines
645 Each line of the message body is stored as single scalar. This is
647 a useful representation for a detailed look in the message body,
648 which is usually line-organized.
649 · Mail::Message::Body::File
651 The message body is stored in an external temporary file. This
653 type of storage is especially useful when the body is large, the
654 total folder is large, or memory is limited.
655 · Mail::Message::Body::InFolder
657 NOT IMPLEMENTED YET. The message is kept in the folder, and is
659 only taken out when the content is changed.
660 · Mail::Message::Body::External
662 NOT IMPLEMENTED YET. The message is kept in a separate file,
664 usually because the message body is large. The difference with the
665 "::External" object is that this external storage stays this way
666 between closing and opening of a folder. The "::External" object
667 only uses a file when the folder is open.
668 Complex bodies
670 · Mail::Message::Body::Delayed
672 The message-body is not yet read, but the exact location of the
674 body is known so the message can be read when needed. This is part
675 of the lazy extraction mechanism. Once extracted, the object can
676 become any simple or complex body.
677 · Mail::Message::Body::Multipart
679 The message body contains a set of sub-messages (which can contain
681 multipart bodies themselves). Each sub-message is an instance of
682 Mail::Message::Part, which is an extension of Mail::Message.
683 · Mail::Message::Body::Nested
685 Nested messages, like "message/rfc822": they contain a message in
687 the body. For most code, they simply behave like multiparts.
688 The body of a message can be stored in many ways. Roughly, the
690 implementations can be split in two groups: the data collectors and the
691 complex bodies. The primer implement various ways to access data, and
692 are full compatible: they only differ in performance and memory
693 footprint under different circumstances. The latter are created to
694 handle complex multiparts and lazy extraction.
695 Character encoding PERL
697 A body object can be part of a message, or stand-alone. In case it is
698 a part of a message, the "transport encoding" and the content must be
699 in a shape that the data can be transported via SMTP.
700 However, when you want to process the body data in simple Perl (or when
702 you construct the body data from normal Perl strings), you need to be
703 aware of Perl's internal representation of strings. That can either be
704 latin1 or utf8 (not real UTF-8, but something alike, see the
705 perlunicode manual page) So, before you start using the data from an
706 incoming message, do
707 my $body = $msg->decoded;
709 my @lines = $body->lines;
710 Now, the body has character-set 'PERL' (when it is text)
712 When you create a new body which contains text content (the default),
714 it will be created with character-set 'PERL' unless you specify a
715 character-set explicitly.
716 my $body = Mail::Box::Body::Lines->new(data => \@lines);
718 # now mime=text/plain, charset=PERL
719 my $msg = Mail::Message->buildFromBody($body);
721 $msg->body($body);
722 $msg->attach($body); # etc
723 # these all will convert the charset=PERL into real utf-8
724
726 Warning: Charset $name is not known
727 The encoding or decoding of a message body encounters a character
728 set which is not understood by Perl's Encode module.
729 Warning: No decoder defined for transfer encoding $name.
731 The data (message body) is encoded in a way which is not currently
732 understood, therefore no decoding (or recoding) can take place.
733 Warning: No encoder defined for transfer encoding $name.
735 The data (message body) has been decoded, but the required encoding
736 is unknown. The decoded data is returned.
737 Error: Package $package does not implement $method.
739 Fatal error: the specific package (or one of its superclasses) does
740 not implement this method where it should. This message means that
741 some other related classes do implement this method however the
742 class at hand does not. Probably you should investigate this and
743 probably inform the author of the package.
744 Warning: Unknown line terminator $eol ignored
746
748 This module is part of Mail-Box distribution version 2.097, built on
749 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
750
752 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
753 ChangeLog.
754 This program is free software; you can redistribute it and/or modify it
756 under the same terms as Perl itself. See
757 http://www.perl.com/perl/misc/Artistic.html
758perl v5.12.3 2011-01-26 Mail::Message::Body(3)