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 Extends "DESCRIPTION" in Mail::Reporter.
53
55 overload: ""
56 (stringification) Returns the body as string --which will trigger
57 completion-- unless called to produce a string for "Carp". The
58 latter to avoid deep recursions.
59 example: stringification of body
61 print $msg->body; # implicit by print
63 my $body = $msg->body;
65 my $x = "$body"; # explicit by interpolation
66 overload: '==' and '!='
68 (numeric comparison) compares if two references point to the same
69 message. This only produces correct results is both arguments are
70 message references within the same folder.
71 example: use of numeric comparison on a body
73 my $skip = $folder->message(3);
75 foreach my $msg (@$folder)
76 { next if $msg == $skip;
77 $msg->send;
78 }
79 overload: @{}
81 When a body object is used as being an array reference, the lines
82 of the body are returned. This is the same as using lines().
83 example: using a body as array
85 print $body->lines->[1]; # second line
87 print $body->[1]; # same
88 my @lines = $body->lines;
90 my @lines = @$body; # same
91 overload: bool
93 Always returns a true value, which is needed to have overloaded
94 objects to be used as in if($body). Otherwise, "if(defined $body)"
95 would be needed to avoid a runtime error.
96
98 Extends "METHODS" in Mail::Reporter.
99 Constructors
101 Extends "Constructors" in Mail::Reporter.
102 $obj->clone()
104 Return a copy of this body, usually to be included in a cloned
105 message. Use Mail::Message::clone() for a whole message.
106 Mail::Message::Body->new(%options)
108 BE WARNED that, what you specify here are encodings and such which
109 are already in place. The options will not trigger conversions.
110 When you need conversions, first create a body with options which
111 tell what you've got, and then call encode() for what you need.
112 -Option --Defined in --Default
114 based_on undef
115 charset 'PERL'
116 checked <false>
117 content_id undef
118 data undef
119 description undef
120 disposition undef
121 eol 'NATIVE'
122 file undef
123 filename undef
124 log Mail::Reporter 'WARNINGS'
125 message undef
126 mime_type 'text/plain'
127 modified <false>
128 trace Mail::Reporter 'WARNINGS'
129 transfer_encoding 'none'
130 based_on => BODY
132 The information about encodings must be taken from the specified
133 BODY, unless specified differently.
134 charset => CHARSET|'PERL'|<undef>
136 Defines the character-set which is used in the data. Only useful
137 in combination with a "mime_type" which refers to "text" in any
138 shape, which does not contain an explicit charset already. This
139 field is case-insensitive.
140 When a known CHARSET is provided and the mime-type says "text",
142 then the data is expected to be raw octets in that particular
143 encoding (see Encode). When 'PERL' is given, then then the data
144 is in Perl's internal encoding; either cp1252 or utf8. More
145 details in "Character encoding PERL"
146 checked => BOOLEAN
148 Whether the added information has been check not to contain
149 illegal octets with respect to the transfer encoding and mime
150 type. If not checked, and then set as body for a message, it
151 will be.
152 content_id => STRING
154 In multipart/related MIME content, the content_id is required to
155 allow access to the related content via a cid:<...> descriptor of
156 an inline disposition.
157 A "Content-ID" is supposed to be globally unique. As such, it is
159 common to append '@computer.domain' to the end of some unique
160 string. As other content in the multipart/related container also
161 needs to know what this "Content-ID" is, this should be left to
162 the imagination of the person making the content (for now).
163 As a MIME header field, the "Content-ID" string is expected to be
165 inside angle brackets
166 data => ARRAY-OF-LINES | STRING
168 The content of the body. The only way to set the content of a
169 body is during the creation of the body. So if you want to
170 modify the content of a message, you need to create a new body
171 with the new content and add that to the body. The reason behind
172 this, is that correct encodings and body information must be
173 guaranteed. It avoids your hassle in calculating the number of
174 lines in the body, and checking whether bad characters are
175 enclosed in text.
176 Specify a reference to an ARRAY of lines, each terminated by a
178 newline. Or one STRING which may contain multiple lines,
179 separated and terminated by a newline.
180 description => STRING|FIELD
182 Informal information about the body content. The data relates to
183 the "Content-Description" field. Specify a STRING which will
184 become the field content, or a real FIELD.
185 disposition => STRING|FIELD
187 How this message can be decomposed. The data relates to the
188 "Content-Disposition" field. Specify a STRING which will become
189 the field content, or a real FIELD.
190 The content of this field is specified in RFC 1806. The body of
192 the field can be "inline", to indicate that the body is intended
193 to be displayed automatically upon display of the message. Use
194 "attachment" to indicate that they are separate from the main
195 body of the mail message, and that their display should not be
196 automatic, but contingent upon some further action of the user.
197 The "filename" attribute specifies a name to which is suggested
199 to the reader of the message when it is extracted.
200 eol => 'CR'|'LF'|'CRLF'|'NATIVE'
202 Convert the message into having the specified string as line
203 terminator for all lines in the body. "NATIVE" is used to
204 represent the "\n" on the current platform and will be translated
205 in the applicable one.
206 BE WARNED that folders with a non-native encoding may appear on
208 your platform, for instance in Windows folders handled from a
209 UNIX system. The eol encoding has effect on the size of the
210 body!
211 file => FILENAME|FILEHANDLE|IOHANDLE
213 Read the data from the specified file, file handle, or object of
214 type "IO::Handle".
215 filename => FILENAME
217 [3.001] Overrule/set filename for content-disposition
218 log => LEVEL
220 message => MESSAGE
221 The message where this body belongs to.
222 mime_type => STRING|FIELD|MIME
224 The type of data which is added. You may specify a content of a
225 header line as STRING, or a FIELD object. You may also specify a
226 MIME::Type object. In any case, it will be kept internally as a
227 real field (a Mail::Message::Field object). This relates to the
228 "Content-Type" header field.
229 A mime-type specification consists of two parts: a general class
231 ("text", "image", "application", etc) and a specific sub-class.
232 Examples for specific classes with "text" are "plain", "html",
233 and "xml". This field is case-insensitive but case preserving.
234 The default mime-type is "text/plain",
235 modified => BOOLEAN
237 Whether the body is flagged modified, directly from its creation.
238 trace => LEVEL
240 transfer_encoding => STRING|FIELD
241 The encoding that the data has. If the data is to be encoded,
242 than you will have to call encode() after the body is created.
243 That will return a new encoded body. This field is case-
244 insensitive and relates to the "Content-Transfer-Encoding" field
245 in the header.
246 example:
248 my $body = Mail::Message::Body::String->new(file => \*IN,
250 mime_type => 'text/html; charset="ISO-8859-1"');
251 my $body = Mail::Message::Body::Lines->new(data => ['first', $second],
253 charset => 'ISO-10646', transfer_encoding => 'none');
254 my $body = Mail::Message::Body::Lines->new(data => \@lines,
256 transfer_encoding => 'base64');
257 my $body = Mail::Message::Body::Lines->new(file => 'picture.gif',
259 mime_type => 'image/gif', content_id => '<12345@example.com>',
260 disposition => 'inline');
261 Constructing a body
263 $obj->attach($messages, %options)
264 Inherited, see "Constructing a body" in
265 Mail::Message::Body::Construct
266 $obj->charsetDetect(%options)
268 Inherited, see "Constructing a body" in Mail::Message::Body::Encode
269 Mail::Message::Body->charsetDetectAlgorithm( [CODE|undef|METHOD] )
271 Inherited, see "Constructing a body" in Mail::Message::Body::Encode
272 $obj->check()
274 Inherited, see "Constructing a body" in Mail::Message::Body::Encode
275 $obj->concatenate($components)
277 Inherited, see "Constructing a body" in
278 Mail::Message::Body::Construct
279 $obj->decoded(%options)
281 Returns a body, an object which is (a sub-)class of a
282 Mail::Message::Body, which contains a simplified representation of
283 textual data. The returned object may be the object where this is
284 called on, but may also be a new body of any type.
285 my $dec = $body->decoded;
287 is equivalent with
289 my $dec = $body->encode
291 ( mime_type => 'text/plain'
292 , transfer_encoding => 'none'
293 , charset => 'PERL'
294 );
295 The $dec which is returned is a body. Ask with the mimeType()
297 method what is produced. This $dec body is not related to a
298 header.
299 -Option --Default
301 result_type <same as current>
302 result_type => CLASS
304 $obj->encode(%options)
305 Inherited, see "Constructing a body" in Mail::Message::Body::Encode
306 $obj->encoded(%options)
308 Inherited, see "Constructing a body" in Mail::Message::Body::Encode
309 $obj->eol( ['CR'|'LF'|'CRLF'|'NATIVE'] )
311 Returns the character (or characters) which are used to separate
312 lines within this body. When a kind of separator is specified, the
313 body is translated to contain the specified line endings.
314 example:
316 my $body = $msg->decoded->eol('NATIVE');
318 my $char = $msg->decoded->eol;
319 $obj->foreachLine(CODE)
321 Inherited, see "Constructing a body" in
322 Mail::Message::Body::Construct
323 $obj->stripSignature(%options)
325 Inherited, see "Constructing a body" in
326 Mail::Message::Body::Construct
327 $obj->unify($body)
329 Inherited, see "Constructing a body" in Mail::Message::Body::Encode
330 The body
332 $obj->isDelayed()
333 Returns a true or false value, depending on whether the body of
334 this message has been read from file. This can only false for a
335 Mail::Message::Body::Delayed.
336 $obj->isMultipart()
338 Returns whether this message-body contains parts which are messages
339 by themselves.
340 $obj->isNested()
342 Only true for a message body which contains exactly one sub-
343 message: the "Mail::Message::Body::Nested" body type.
344 $obj->message( [$message] )
346 Returns the message (or message part) where this body belongs to,
347 optionally setting it to a new $message first. If "undef" is
348 passed, the body will be disconnected from the message.
349 $obj->partNumberOf($part)
351 Returns a string for multiparts and nested, otherwise an error. It
352 is used in Mail::Message::partNumber().
353 About the payload
355 $obj->charset()
356 Returns the character set which is used in the text body as string.
357 This is part of the result of what the "type" method returns.
358 $obj->checked( [BOOLEAN] )
360 Returns whether the body encoding has been checked or not
361 (optionally after setting the flag to a new value).
362 $obj->contentId( [STRING|$field] )
364 Returns (optionally after setting) the id (unique reference) of a
365 message part. The related header field is "Content-ID". A
366 Mail::Message::Field object is returned (which stringifies into the
367 field content). The field content will be "none" if no disposition
368 was specified.
369 The argument can be a STRING (which is converted into a field), or
371 a fully prepared header $field.
372 $obj->description( [STRING|$field] )
374 Returns (optionally after setting) the informal description of the
375 body content. The related header field is "Content-Description".
376 A Mail::Message::Field object is returned (which stringifies into
377 the field content). The field content will be "none" if no
378 disposition was specified.
379 The argument can be a STRING (which is converted into a field), or
381 a fully prepared header field.
382 $obj->disposition( [STRING|$field] )
384 Returns (optionally after setting) how the message can be disposed
385 (unpacked). The related header field is "Content-Disposition". A
386 Mail::Message::Field object is returned (which stringifies into the
387 field content). The field content will be "none" if no disposition
388 was specified.
389 The argument can be a STRING (which is converted into a field), or
391 a fully prepared header field.
392 $obj->dispositionFilename( [$directory] )
394 Inherited, see "About the payload" in Mail::Message::Body::Encode
395 $obj->isBinary()
397 Inherited, see "About the payload" in Mail::Message::Body::Encode
398 $obj->isText()
400 Inherited, see "About the payload" in Mail::Message::Body::Encode
401 $obj->mimeType()
403 Returns a MIME::Type object which is related to this body's type.
404 This differs from the "type" method, which results in a
405 Mail::Message::Field.
406 example:
408 if($body->mimeType eq 'text/html') {...}
410 print $body->mimeType->simplified;
411 $obj->nrLines()
413 Returns the number of lines in the message body. For multi-part
414 messages, this includes the header lines and boundaries of all the
415 parts.
416 $obj->size()
418 The total number of bytes in the message body. The size of the body
419 is computed in the shape it is in. For example, if this is a base64
420 encoded message, the size of the encoded data is returned; you may
421 want to call Mail::Message::decoded() first.
422 $obj->transferEncoding( [STRING|$field] )
424 Returns the transfer-encoding of the data within this body as
425 Mail::Message::Field (which stringifies to its content). If it
426 needs to be changed, call the encode() or Mail::Message::Body
427 subroutine ecoded method. When no encoding is present, the field
428 contains the text "none".
429 The optional STRING or $field enforces a new encoding to be set,
431 without the actual required translations.
432 example:
434 my $transfer = $msg->decoded->transferEncoding;
436 $transfer->print; # --> Content-Encoding: base64
437 print $transfer; # --> base64
438 if($msg->body->transferEncoding eq 'none') {...}
440 $obj->type( [STRING|$field] )
442 Returns the type of information the body contains as
443 Mail::Message::Field object. The type is taken from the header
444 field "Content-Type". If the header did not contain that field,
445 then you will get a default field containing "text/plain".
446 You usually can better use mimeType(), because that will return a
448 clever object with type information.
449 example:
451 my $msg = $folder->message(6);
453 $msg->get('Content-Type')->print;
454 # --> Content-Type: text/plain; charset="us-ascii"
455 my $content = $msg->decoded;
457 my $type = $content->type;
458 print "This is a $type message\n";
460 # --> This is a text/plain; charset="us-ascii" message
461 print "This is a ", $type->body, "message\n";
463 # --> This is a text/plain message
464 print "Comment: ", $type->comment, "\n";
466 # --> Comment: charset="us-ascii"
467 Access to the payload
469 $obj->endsOnNewline()
470 Returns whether the last line of the body is terminated by a new-
471 line (in transport it will become a CRLF). An empty body will
472 return true as well: the newline comes from the line before it.
473 $obj->file()
475 Return the content of the body as a file handle. The returned
476 stream may be a real file, or a simulated file in any form that
477 Perl supports. While you may not be able to write to the file
478 handle, you can read from it.
479 WARNING: Even if the file handle supports writing, do not write to
481 the file handle. If you do, some of the internal values of the
482 Mail::Message::Body may not be updated.
483 $obj->lines()
485 Return the content of the body as a list of lines (in LIST context)
486 or a reference to an array of lines (in SCALAR context). In scalar
487 context the array of lines is cached to avoid needless copying and
488 therefore provide much faster access for large messages.
489 To just get the number of lines in the body, use the nrLines()
491 method, which is usually much more efficient.
492 BE WARNED: For some types of bodies the reference will refer to the
494 original data. You must not change the referenced data! If you do,
495 some of the essential internal variables of the Mail::Message::Body
496 may not be updated.
497 example:
499 my @lines = $body->lines; # copies lines
501 my $line3 = ($body->lines)[3] # only one copy
502 print $lines[0];
503 my $linesref = $body->lines; # reference to originals
505 my $line3 = $body->lines->[3] # only one copy (faster)
506 print $linesref->[0];
507 print $body->[0]; # by overloading
509 $obj->print( [$fh] )
511 Print the body to the specified $fh (defaults to the selected
512 handle). The handle may be a GLOB, an IO::File object, or... any
513 object with a print() method will do. Nothing useful is returned.
514 $obj->printEscapedFrom($fh)
516 Print the body to the specified $fh but all lines which start with
517 'From ' (optionally already preceded by >'s) will habe an > added
518 in front. Nothing useful is returned.
519 $obj->string()
521 Return the content of the body as a scalar (a single string). This
522 is a copy of the internally kept information.
523 example:
525 my $text = $body->string;
527 print "Body: $body\n"; # by overloading
528 $obj->stripTrailingNewline()
530 Remove the newline from the last line, or the last line if it does
531 not contain anything else than a newline.
532 $obj->write(%options)
534 Write the content of the body to a file. Be warned that you may
535 want to decode the body before writing it!
536 -Option --Default
538 filename <required>
539 filename => FILENAME
541 example: write the data to a file
543 use File::Temp;
545 my $fn = tempfile;
546 $message->decoded->write(filename => $fn)
547 or die "Couldn't write to $fn: $!\n";
548 example: using the content-disposition information to write
550 use File::Temp;
552 my $dir = tempdir; mkdir $dir or die;
553 my $fn = $message->body->dispositionFilename($dir);
554 $message->decoded->write(filename => $fn)
555 or die "Couldn't write to $fn: $!\n";
556 Internals
558 $obj->addTransferEncHandler( $name, <$class|$object> )
559 Mail::Message::Body->addTransferEncHandler( $name, <$class|$object> )
560 Inherited, see "Internals" in Mail::Message::Body::Encode
561 $obj->contentInfoFrom($head)
563 Transfer the body related info from the header into this body.
564 $obj->contentInfoTo($head)
566 Copy the content information (the "Content-*" fields) into the
567 specified $head. The body was created from raw data without the
568 required information, which must be added. See also
569 contentInfoFrom().
570 $obj->fileLocation( [$begin, $end] )
572 The location of the body in the file. Returned a list containing
573 begin and end. The begin is the offsets of the first byte if the
574 folder used for this body. The end is the offset of the first byte
575 of the next message.
576 $obj->getTransferEncHandler($type)
578 Inherited, see "Internals" in Mail::Message::Body::Encode
579 $obj->isModified()
581 Returns whether the body has changed.
582 $obj->load()
584 Be sure that the body is loaded. This returns the loaded body.
585 $obj->modified( [BOOLEAN] )
587 Change the body modification flag. This will force a re-write of
588 the body to a folder file when it is closed. It is quite dangerous
589 to change the body: the same body may be shared between messages
590 within your program.
591 Especially be warned that you have to change the message-id when
593 you change the body of the message: no two messages should have the
594 same id.
595 Without value, the current setting is returned, although you can
597 better use isModified().
598 $obj->moveLocation( [$distance] )
600 Move the registration of the message to a new location over
601 $distance. This is called when the message is written to a new
602 version of the same folder-file.
603 $obj->read( $parser, $head, $bodytype, [$chars, [$lines]] )
605 Read the body with the $parser from file. The implementation of
606 this method will differ between types of bodies. The $bodytype
607 argument is a class name or a code reference of a routine which can
608 produce a class name, and is used in multipart bodies to determine
609 the type of the body for each part.
610 The $chars argument is the estimated number of bytes in the body,
612 or "undef" when this is not known. This data can sometimes be
613 derived from the header (the "Content-Length" line) or file-size.
614 The second argument is the estimated number of $lines of the body.
616 It is less useful than the $chars but may be of help determining
617 whether the message separator is trustworthy. This value may be
618 found in the "Lines" field of the header.
619 Error handling
621 Extends "Error handling" in Mail::Reporter.
622 $obj->AUTOLOAD()
624 When an unknown method is called on a message body object, this may
625 not be problematic. For performance reasons, some methods are
626 implemented in separate files, and only demand-loaded. If this
627 delayed compilation of additional modules does not help, an error
628 will be produced.
629 $obj->addReport($object)
631 Inherited, see "Error handling" in Mail::Reporter
632 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
634 $callback] )
635 Mail::Message::Body->defaultTrace( [$level]|[$loglevel,
636 $tracelevel]|[$level, $callback] )
637 Inherited, see "Error handling" in Mail::Reporter
638 $obj->errors()
640 Inherited, see "Error handling" in Mail::Reporter
641 $obj->log( [$level, [$strings]] )
643 Mail::Message::Body->log( [$level, [$strings]] )
644 Inherited, see "Error handling" in Mail::Reporter
645 $obj->logPriority($level)
647 Mail::Message::Body->logPriority($level)
648 Inherited, see "Error handling" in Mail::Reporter
649 $obj->logSettings()
651 Inherited, see "Error handling" in Mail::Reporter
652 $obj->notImplemented()
654 Inherited, see "Error handling" in Mail::Reporter
655 $obj->report( [$level] )
657 Inherited, see "Error handling" in Mail::Reporter
658 $obj->reportAll( [$level] )
660 Inherited, see "Error handling" in Mail::Reporter
661 $obj->trace( [$level] )
663 Inherited, see "Error handling" in Mail::Reporter
664 $obj->warnings()
666 Inherited, see "Error handling" in Mail::Reporter
667 Cleanup
669 Extends "Cleanup" in Mail::Reporter.
670 $obj->DESTROY()
672 Inherited, see "Cleanup" in Mail::Reporter
673
675 Access to the body
676 A body can be contained in a message, but may also live without a
677 message. In both cases it stores data, and the same questions can be
678 asked: what type of data it is, how many bytes and lines, what encoding
679 is used. Any body can be encoded and decoded, returning a new body
680 object. However, bodies which are part of a message will always be in
681 a shape that they can be written to a file or send to somewhere: they
682 will be encoded if needed.
683 . Example
685 my $body = Mail::Message::Body::String->new(mime_type => 'image/gif');
687 $body->print(\*OUT); # this is binary image data...
688 my $encoded = $message->body($body);
690 $encoded->print(\*OUT); # ascii data, encoded image
691 Now encoded refers to the body of the $message which is the content of
693 $body in a shape that it can be transmitted. Usually "base64" encoding
694 is used.
695 Body class implementation
697 The body of a message can be stored in many ways. Roughly, the
698 implementations can be split in two groups: the data collectors and the
699 complex bodies. The primer implement various ways to access data, and
700 are full compatible: they only differ in performance and memory
701 footprint under different circumstances. The latter are created to
702 handle complex multiparts and lazy extraction.
703 Data collector bodies
705 • Mail::Message::Body::String
707 The whole message body is stored in one scalar. Small messages can
709 be contained this way without performance penalties.
710 • Mail::Message::Body::Lines
712 Each line of the message body is stored as single scalar. This is
714 a useful representation for a detailed look in the message body,
715 which is usually line-organized.
716 • Mail::Message::Body::File
718 The message body is stored in an external temporary file. This
720 type of storage is especially useful when the body is large, the
721 total folder is large, or memory is limited.
722 • Mail::Message::Body::InFolder
724 NOT IMPLEMENTED YET. The message is kept in the folder, and is
726 only taken out when the content is changed.
727 • Mail::Message::Body::External
729 NOT IMPLEMENTED YET. The message is kept in a separate file,
731 usually because the message body is large. The difference with the
732 "::External" object is that this external storage stays this way
733 between closing and opening of a folder. The "::External" object
734 only uses a file when the folder is open.
735 Complex bodies
737 • Mail::Message::Body::Delayed
739 The message-body is not yet read, but the exact location of the
741 body is known so the message can be read when needed. This is part
742 of the lazy extraction mechanism. Once extracted, the object can
743 become any simple or complex body.
744 • Mail::Message::Body::Multipart
746 The message body contains a set of sub-messages (which can contain
748 multipart bodies themselves). Each sub-message is an instance of
749 Mail::Message::Part, which is an extension of Mail::Message.
750 • Mail::Message::Body::Nested
752 Nested messages, like "message/rfc822": they contain a message in
754 the body. For most code, they simply behave like multiparts.
755 Character encoding PERL
757 A body object can be part of a message, or stand-alone. In case it is
758 a part of a message, the "transport encoding" and the content must be
759 in a shape that the data can be transported via SMTP.
760 However, when you want to process the body data in simple Perl (or when
762 you construct the body data from normal Perl strings), you need to be
763 aware of Perl's internal representation of strings. That can either be
764 cp1252 (extended latin1) or utf8 (not real UTF-8, but something alike,
765 see the perlunicode manual page) So, before you start using the data
766 from an incoming message, do
767 my $body = $msg->decoded;
769 my @lines = $body->lines;
770 Now, the body has character-set 'PERL' (when it is text)
772 When you create a new body which contains text content (the default),
774 it will be created with character-set 'PERL' unless you specify a
775 character-set explicitly.
776 my $body = Mail::Box::Body::Lines->new(data => \@lines);
778 # now mime=text/plain, charset=PERL
779 my $msg = Mail::Message->buildFromBody($body);
781 $msg->body($body);
782 $msg->attach($body); # etc
783 # these all will convert the charset=PERL into real utf-8,
784 # cp1252 or us-ascii, which depends on the characters found.
785 Autodetection of character-set
787 This "Body" object represents data as part of an existing message, or
789 to become part of a message. The body can be in two states:
790 1. ready to be processed textually, using Perl's string operations
792 2. raw bytes read or to be written
793 In the first case, the body content has no transfer encoding on it
795 ("none"), and the character-set is "PERL". In the second version, the
796 body may have transfer encoding and has an (IANA listed) charset on it
797 (defaults to "us-ascii")
798 Using encode() (maybe via Mail::Message::Body subroutine decode), you
800 can convert bodies from one state into a different one. In one go, you
801 can change the transfer-encoding, the character-set, or whether it is
802 in PERL string format or raw (in bytes).
803 [3.013] A serious problem is created when a conversion is needed, while
805 the input or output character-set is not explicitly known. The email
806 RFCs state that the default is "us-ascii". However, in the real world
807 it can be anything. Therefore, in such situations autodetection kicks
808 in.
809 1. When a Body is read (using Mail::Message::read() and friends), the
811 character-set may stay undefined until transfer-decoding has been
812 applicied. At that moment, (configurable auto-detection) is
813 applied;
814 2. When a Body is created witin the program, without specific
816 character-set, it will use 'PERL';
817 3. When a Body is written, the requested character-set is not
819 specified, and the current character-set is "PERL", then auto-
820 dectection is used. This may result in "us-ascii", "cp1252" and
821 "utf-8";
822 4. In all other cases, the character-set is known so "easy".
824
826 Warning: Charset $name is not known
827 The encoding or decoding of a message body encounters a character
828 set which is not understood by Perl's Encode module.
829 Warning: No decoder defined for transfer encoding $name.
831 The data (message body) is encoded in a way which is not currently
832 understood, therefore no decoding (or recoding) can take place.
833 Warning: No encoder defined for transfer encoding $name.
835 The data (message body) has been decoded, but the required encoding
836 is unknown. The decoded data is returned.
837 Error: Package $package does not implement $method.
839 Fatal error: the specific package (or one of its superclasses) does
840 not implement this method where it should. This message means that
841 some other related classes do implement this method however the
842 class at hand does not. Probably you should investigate this and
843 probably inform the author of the package.
844 Warning: Unknown line terminator $eol ignored
846
848 This module is part of Mail-Message distribution version 3.013, built
849 on June 24, 2023. Website: http://perl.overmeer.net/CPAN/
850
852 Copyrights 2001-2023 by [Mark Overmeer <markov@cpan.org>]. For other
853 contributors see ChangeLog.
854 This program is free software; you can redistribute it and/or modify it
856 under the same terms as Perl itself. See http://dev.perl.org/licenses/
857perl v5.38.0 2023-07-20 Mail::Message::Body(3)