1Mail::Message::Body(3)User Contributed Perl DocumentationMail::Message::Body(3)
2
3
4

NAME

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

INHERITANCE

9        Mail::Message::Body has extra code in
10          Mail::Message::Body::Construct
11          Mail::Message::Body::Encode
12
13        Mail::Message::Body
14          is a Mail::Reporter
15
16        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
23        Mail::Message::Body is realized by
24          Mail::Message::Body::Delayed
25

SYNOPSIS

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

DESCRIPTION

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
47       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
52       Extends "DESCRIPTION" in Mail::Reporter.
53

OVERLOADED

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
60           example: stringification of body
61
62            print $msg->body;   # implicit by print
63
64            my $body = $msg->body;
65            my $x    = "$body"; # explicit by interpolation
66
67       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
72           example: use of numeric comparison on a body
73
74            my $skip = $folder->message(3);
75            foreach my $msg (@$folder)
76            {   next if $msg == $skip;
77                $msg->send;
78            }
79
80       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
84           example: using a body as array
85
86            print $body->lines->[1];  # second line
87            print $body->[1];         # same
88
89            my @lines = $body->lines;
90            my @lines = @$body;       # same
91
92       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
95           $body)" would be needed to avoid a runtime error.
96

METHODS

98       Extends "METHODS" in Mail::Reporter.
99
100   Constructors
101       Extends "Constructors" in Mail::Reporter.
102
103       $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
107       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
113            -Option           --Defined in     --Default
114             based_on                            undef
115             charset                             'PERL' or <undef>
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
131           based_on => BODY
132             The information about encodings must be taken from the specified
133             BODY, unless specified differently.
134
135           charset => CHARSET|'PERL'
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
141             When a known CHARSET is provided and the mime type says "text",
142             then the data is expected to be bytes in that particular encoding
143             (see Encode).  When 'PERL' is given, then then the data is in
144             Perl's internal encoding (either latin1 or utf8, you shouldn't
145             know!) More details in "Character encoding PERL"
146
147           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
153           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
158             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
164             As a MIME header field, the "Content-ID" string is expected to be
165             inside angle brackets
166
167           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
177             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
181           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
186           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
191             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
198             The "filename" attribute specifies a name to which is suggested
199             to the reader of the message when it is extracted.
200
201           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
207             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
212           file => FILENAME|FILEHANDLE|IOHANDLE
213             Read the data from the specified file, file handle, or object of
214             type "IO::Handle".
215
216           filename => FILENAME
217             [3.001] Overrule/set filename for content-disposition
218
219           log => LEVEL
220           message => MESSAGE
221             The message where this body belongs to.
222
223           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
230             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
236           modified => BOOLEAN
237             Whether the body is flagged modified, directly from its creation.
238
239           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
247           example:
248
249            my $body = Mail::Message::Body::String->new(file => \*IN,
250               mime_type => 'text/html; charset="ISO-8859-1"');
251
252            my $body = Mail::Message::Body::Lines->new(data => ['first', $second],
253               charset => 'ISO-10646', transfer_encoding => 'none');
254
255            my $body = Mail::Message::Body::Lines->new(data => \@lines,
256               transfer_encoding => 'base64');
257
258            my $body = Mail::Message::Body::Lines->new(file => 'picture.gif',
259               mime_type => 'image/gif', content_id => '<12345@example.com>',
260               disposition => 'inline');
261
262   Constructing a body
263       $obj->attach($messages, %options)
264           Inherited, see "Constructing a body" in
265           Mail::Message::Body::Construct
266
267       $obj->check()
268           Inherited, see "Constructing a body" in Mail::Message::Body::Encode
269
270       $obj->concatenate($components)
271           Inherited, see "Constructing a body" in
272           Mail::Message::Body::Construct
273
274       $obj->decoded(%options)
275           Returns a body, an object which is (a sub-)class of a
276           Mail::Message::Body, which contains a simplified representation of
277           textual data.  The returned object may be the object where this is
278           called on, but may also be a new body of any type.
279
280            my $dec = $body->decoded;
281
282           is equivalent with
283
284            my $dec = $body->encode
285              ( mime_type         => 'text/plain'
286              , transfer_encoding => 'none'
287              , charset           => 'PERL'
288              );
289
290           The $dec which is returned is a body.  Ask with the mimeType()
291           method what is produced.  This $dec body is not related to a
292           header.
293
294            -Option     --Default
295             result_type  <same as current>
296
297           result_type => CLASS
298       $obj->encode(%options)
299           Inherited, see "Constructing a body" in Mail::Message::Body::Encode
300
301       $obj->encoded()
302           Inherited, see "Constructing a body" in Mail::Message::Body::Encode
303
304       $obj->eol( ['CR'|'LF'|'CRLF'|'NATIVE'] )
305           Returns the character (or characters) which are used to separate
306           lines within this body.  When a kind of separator is specified, the
307           body is translated to contain the specified line endings.
308
309           example:
310
311            my $body = $msg->decoded->eol('NATIVE');
312            my $char = $msg->decoded->eol;
313
314       $obj->foreachLine(CODE)
315           Inherited, see "Constructing a body" in
316           Mail::Message::Body::Construct
317
318       $obj->stripSignature(%options)
319           Inherited, see "Constructing a body" in
320           Mail::Message::Body::Construct
321
322       $obj->unify($body)
323           Inherited, see "Constructing a body" in Mail::Message::Body::Encode
324
325   The body
326       $obj->isDelayed()
327           Returns a true or false value, depending on whether the body of
328           this message has been read from file.  This can only false for a
329           Mail::Message::Body::Delayed.
330
331       $obj->isMultipart()
332           Returns whether this message-body contains parts which are messages
333           by themselves.
334
335       $obj->isNested()
336           Only true for a message body which contains exactly one sub-
337           message: the "Mail::Message::Body::Nested" body type.
338
339       $obj->message( [$message] )
340           Returns the message (or message part) where this body belongs to,
341           optionally setting it to a new $message first.  If "undef" is
342           passed, the body will be disconnected from the message.
343
344       $obj->partNumberOf($part)
345           Returns a string for multiparts and nested, otherwise an error.  It
346           is used in Mail::Message::partNumber().
347
348   About the payload
349       $obj->charset()
350           Returns the character set which is used in the text body as string.
351           This is part of the result of what the "type" method returns.
352
353       $obj->checked( [BOOLEAN] )
354           Returns whether the body encoding has been checked or not
355           (optionally after setting the flag to a new value).
356
357       $obj->contentId( [STRING|$field] )
358           Returns (optionally after setting) the id (unique reference) of a
359           message part.  The related header field is "Content-ID".  A
360           Mail::Message::Field object is returned (which stringifies into the
361           field content).  The field content will be "none" if no disposition
362           was specified.
363
364           The argument can be a STRING (which is converted into a field), or
365           a fully prepared header $field.
366
367       $obj->description( [STRING|$field] )
368           Returns (optionally after setting) the informal description of the
369           body content.  The related header field is "Content-Description".
370           A Mail::Message::Field object is returned (which stringifies into
371           the field content).  The field content will be "none" if no
372           disposition was specified.
373
374           The argument can be a STRING (which is converted into a field), or
375           a fully prepared header field.
376
377       $obj->disposition( [STRING|$field] )
378           Returns (optionally after setting) how the message can be disposed
379           (unpacked).  The related header field is "Content-Disposition".  A
380           Mail::Message::Field object is returned (which stringifies into the
381           field content).  The field content will be "none" if no disposition
382           was specified.
383
384           The argument can be a STRING (which is converted into a field), or
385           a fully prepared header field.
386
387       $obj->dispositionFilename( [$directory] )
388           Inherited, see "About the payload" in Mail::Message::Body::Encode
389
390       $obj->isBinary()
391           Inherited, see "About the payload" in Mail::Message::Body::Encode
392
393       $obj->isText()
394           Inherited, see "About the payload" in Mail::Message::Body::Encode
395
396       $obj->mimeType()
397           Returns a MIME::Type object which is related to this body's type.
398           This differs from the "type" method, which results in a
399           Mail::Message::Field.
400
401           example:
402
403            if($body->mimeType eq 'text/html') {...}
404            print $body->mimeType->simplified;
405
406       $obj->nrLines()
407           Returns the number of lines in the message body.  For multi-part
408           messages, this includes the header lines and boundaries of all the
409           parts.
410
411       $obj->size()
412           The total number of bytes in the message body. The size of the body
413           is computed in the shape it is in. For example, if this is a base64
414           encoded message, the size of the encoded data is returned; you may
415           want to call Mail::Message::decoded() first.
416
417       $obj->transferEncoding( [STRING|$field] )
418           Returns the transfer-encoding of the data within this body as
419           Mail::Message::Field (which stringifies to its content).  If it
420           needs to be changed, call the encode() or decoded() method.  When
421           no encoding is present, the field contains the text "none".
422
423           The optional STRING or $field enforces a new encoding to be set,
424           without the actual required translations.
425
426           example:
427
428            my $transfer = $msg->decoded->transferEncoding;
429            $transfer->print;   # --> Content-Encoding: base64
430            print $transfer;    # --> base64
431
432            if($msg->body->transferEncoding eq 'none') {...}
433
434       $obj->type( [STRING|$field] )
435           Returns the type of information the body contains as
436           Mail::Message::Field object.  The type is taken from the header
437           field "Content-Type". If the header did not contain that field,
438           then you will get a default field containing "text/plain".
439
440           You usually can better use mimeType(), because that will return a
441           clever object with type information.
442
443           example:
444
445            my $msg     = $folder->message(6);
446            $msg->get('Content-Type')->print;
447               # --> Content-Type: text/plain; charset="us-ascii"
448
449            my $content = $msg->decoded;
450            my $type    = $content->type;
451
452            print "This is a $type message\n";
453               # --> This is a text/plain; charset="us-ascii" message
454
455            print "This is a ", $type->body, "message\n";
456               # --> This is a text/plain message
457
458            print "Comment: ", $type->comment, "\n";
459               # --> Comment: charset="us-ascii"
460
461   Access to the payload
462       $obj->endsOnNewline()
463           Returns whether the last line of the body is terminated by a new-
464           line (in transport it will become a CRLF).  An empty body will
465           return true as well: the newline comes from the line before it.
466
467       $obj->file()
468           Return the content of the body as a file handle.  The returned
469           stream may be a real file, or a simulated file in any form that
470           Perl supports.  While you may not be able to write to the file
471           handle, you can read from it.
472
473           WARNING: Even if the file handle supports writing, do not write to
474           the file handle. If you do, some of the internal values of the
475           Mail::Message::Body may not be updated.
476
477       $obj->lines()
478           Return the content of the body as a list of lines (in LIST context)
479           or a reference to an array of lines (in SCALAR context).  In scalar
480           context the array of lines is cached to avoid needless copying and
481           therefore provide much faster access for large messages.
482
483           To just get the number of lines in the body, use the nrLines()
484           method, which is usually much more efficient.
485
486           BE WARNED: For some types of bodies the reference will refer to the
487           original data. You must not change the referenced data! If you do,
488           some of the essential internal variables of the Mail::Message::Body
489           may not be updated.
490
491           example:
492
493            my @lines    = $body->lines;     # copies lines
494            my $line3    = ($body->lines)[3] # only one copy
495            print $lines[0];
496
497            my $linesref = $body->lines;     # reference to originals
498            my $line3    = $body->lines->[3] # only one copy (faster)
499            print $linesref->[0];
500
501            print $body->[0];                # by overloading
502
503       $obj->print( [$fh] )
504           Print the body to the specified $fh (defaults to the selected
505           handle).  The handle may be a GLOB, an IO::File object, or... any
506           object with a "print()" method will do.  Nothing useful is
507           returned.
508
509       $obj->printEscapedFrom($fh)
510           Print the body to the specified $fh but all lines which start with
511           'From ' (optionally already preceded by >'s) will habe an > added
512           in front.  Nothing useful is returned.
513
514       $obj->string()
515           Return the content of the body as a scalar (a single string).  This
516           is a copy of the internally kept information.
517
518           example:
519
520            my $text = $body->string;
521            print "Body: $body\n";     # by overloading
522
523       $obj->stripTrailingNewline()
524           Remove the newline from the last line, or the last line if it does
525           not contain anything else than a newline.
526
527       $obj->write(%options)
528           Write the content of the body to a file.  Be warned that you may
529           want to decode the body before writing it!
530
531            -Option  --Default
532             filename  <required>
533
534           filename => FILENAME
535
536           example: write the data to a file
537
538            use File::Temp;
539            my $fn = tempfile;
540            $message->decoded->write(filename => $fn)
541               or die "Couldn't write to $fn: $!\n";
542
543           example: using the content-disposition information to write
544
545            use File::Temp;
546            my $dir = tempdir; mkdir $dir or die;
547            my $fn  = $message->body->dispositionFilename($dir);
548            $message->decoded->write(filename => $fn)
549               or die "Couldn't write to $fn: $!\n";
550
551   Internals
552       $obj->addTransferEncHandler( $name, <$class|$object> )
553       Mail::Message::Body->addTransferEncHandler( $name, <$class|$object> )
554           Inherited, see "Internals" in Mail::Message::Body::Encode
555
556       $obj->contentInfoFrom($head)
557           Transfer the body related info from the header into this body.
558
559       $obj->contentInfoTo($head)
560           Copy the content information (the "Content-*" fields) into the
561           specified $head.  The body was created from raw data without the
562           required information, which must be added.  See also
563           contentInfoFrom().
564
565       $obj->fileLocation( [$begin, $end] )
566           The location of the body in the file.  Returned a list containing
567           begin and end.  The begin is the offsets of the first byte if the
568           folder used for this body.  The end is the offset of the first byte
569           of the next message.
570
571       $obj->getTransferEncHandler($type)
572           Inherited, see "Internals" in Mail::Message::Body::Encode
573
574       $obj->isModified()
575           Returns whether the body has changed.
576
577       $obj->load()
578           Be sure that the body is loaded.  This returns the loaded body.
579
580       $obj->modified( [BOOLEAN] )
581           Change the body modification flag.  This will force a re-write of
582           the body to a folder file when it is closed.  It is quite dangerous
583           to change the body: the same body may be shared between messages
584           within your program.
585
586           Especially be warned that you have to change the message-id when
587           you change the body of the message: no two messages should have the
588           same id.
589
590           Without value, the current setting is returned, although you can
591           better use isModified().
592
593       $obj->moveLocation( [$distance] )
594           Move the registration of the message to a new location over
595           $distance.  This is called when the message is written to a new
596           version of the same folder-file.
597
598       $obj->read( $parser, $head, $bodytype, [$chars, [$lines]] )
599           Read the body with the $parser from file. The implementation of
600           this method will differ between types of bodies.  The $bodytype
601           argument is a class name or a code reference of a routine which can
602           produce a class name, and is used in multipart bodies to determine
603           the type of the body for each part.
604
605           The $chars argument is the estimated number of bytes in the body,
606           or "undef" when this is not known.  This data can sometimes be
607           derived from the header (the "Content-Length" line) or file-size.
608
609           The second argument is the estimated number of $lines of the body.
610           It is less useful than the $chars but may be of help determining
611           whether the message separator is trustworthy.  This value may be
612           found in the "Lines" field of the header.
613
614   Error handling
615       Extends "Error handling" in Mail::Reporter.
616
617       $obj->AUTOLOAD()
618           When an unknown method is called on a message body object, this may
619           not be problematic.  For performance reasons, some methods are
620           implemented in separate files, and only demand-loaded.  If this
621           delayed compilation of additional modules does not help, an error
622           will be produced.
623
624       $obj->addReport($object)
625           Inherited, see "Error handling" in Mail::Reporter
626
627       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
628       $callback] )
629       Mail::Message::Body->defaultTrace( [$level]|[$loglevel,
630       $tracelevel]|[$level, $callback] )
631           Inherited, see "Error handling" in Mail::Reporter
632
633       $obj->errors()
634           Inherited, see "Error handling" in Mail::Reporter
635
636       $obj->log( [$level, [$strings]] )
637       Mail::Message::Body->log( [$level, [$strings]] )
638           Inherited, see "Error handling" in Mail::Reporter
639
640       $obj->logPriority($level)
641       Mail::Message::Body->logPriority($level)
642           Inherited, see "Error handling" in Mail::Reporter
643
644       $obj->logSettings()
645           Inherited, see "Error handling" in Mail::Reporter
646
647       $obj->notImplemented()
648           Inherited, see "Error handling" in Mail::Reporter
649
650       $obj->report( [$level] )
651           Inherited, see "Error handling" in Mail::Reporter
652
653       $obj->reportAll( [$level] )
654           Inherited, see "Error handling" in Mail::Reporter
655
656       $obj->trace( [$level] )
657           Inherited, see "Error handling" in Mail::Reporter
658
659       $obj->warnings()
660           Inherited, see "Error handling" in Mail::Reporter
661
662   Cleanup
663       Extends "Cleanup" in Mail::Reporter.
664
665       $obj->DESTROY()
666           Inherited, see "Cleanup" in Mail::Reporter
667

DETAILS

669   Access to the body
670       A body can be contained in a message, but may also live without a
671       message.  In both cases it stores data, and the same questions can be
672       asked: what type of data it is, how many bytes and lines, what encoding
673       is used.  Any body can be encoded and decoded, returning a new body
674       object.  However, bodies which are part of a message will always be in
675       a shape that they can be written to a file or send to somewhere: they
676       will be encoded if needed.
677
678       . Example
679
680        my $body    = Mail::Message::Body::String->new(mime_type => 'image/gif');
681        $body->print(\*OUT);    # this is binary image data...
682
683        my $encoded = $message->body($body);
684        $encoded->print(\*OUT); # ascii data, encoded image
685
686       Now encoded refers to the body of the $message which is the content of
687       $body in a shape that it can be transmitted.  Usually "base64" encoding
688       is used.
689
690   Body class implementation
691       The body of a message can be stored in many ways.  Roughly, the
692       implementations can be split in two groups: the data collectors and the
693       complex bodies. The primer implement various ways to access data, and
694       are full compatible: they only differ in performance and memory
695       footprint under different circumstances.  The latter are created to
696       handle complex multiparts and lazy extraction.
697
698       Data collector bodies
699
700       ·   Mail::Message::Body::String
701
702           The whole message body is stored in one scalar.  Small messages can
703           be contained this way without performance penalties.
704
705       ·   Mail::Message::Body::Lines
706
707           Each line of the message body is stored as single scalar.  This is
708           a useful representation for a detailed look in the message body,
709           which is usually line-organized.
710
711       ·   Mail::Message::Body::File
712
713           The message body is stored in an external temporary file.  This
714           type of storage is especially useful when the body is large, the
715           total folder is large, or memory is limited.
716
717       ·   Mail::Message::Body::InFolder
718
719           NOT IMPLEMENTED YET.  The message is kept in the folder, and is
720           only taken out when the content is changed.
721
722       ·   Mail::Message::Body::External
723
724           NOT IMPLEMENTED YET.  The message is kept in a separate file,
725           usually because the message body is large.  The difference with the
726           "::External" object is that this external storage stays this way
727           between closing and opening of a folder. The "::External" object
728           only uses a file when the folder is open.
729
730       Complex bodies
731
732       ·   Mail::Message::Body::Delayed
733
734           The message-body is not yet read, but the exact location of the
735           body is known so the message can be read when needed.  This is part
736           of the lazy extraction mechanism.  Once extracted, the object can
737           become any simple or complex body.
738
739       ·   Mail::Message::Body::Multipart
740
741           The message body contains a set of sub-messages (which can contain
742           multipart bodies themselves).  Each sub-message is an instance of
743           Mail::Message::Part, which is an extension of Mail::Message.
744
745       ·   Mail::Message::Body::Nested
746
747           Nested messages, like "message/rfc822": they contain a message in
748           the body.  For most code, they simply behave like multiparts.
749
750   Character encoding PERL
751       A body object can be part of a message, or stand-alone.  In case it is
752       a part of a message, the "transport encoding" and the content must be
753       in a shape that the data can be transported via SMTP.
754
755       However, when you want to process the body data in simple Perl (or when
756       you construct the body data from normal Perl strings), you need to be
757       aware of Perl's internal representation of strings. That can either be
758       latin1 or utf8 (not real UTF-8, but something alike, see the
759       perlunicode manual page)  So, before you start using the data from an
760       incoming message, do
761
762           my $body  = $msg->decoded;
763           my @lines = $body->lines;
764
765       Now, the body has character-set 'PERL' (when it is text)
766
767       When you create a new body which contains text content (the default),
768       it will be created with character-set 'PERL' unless you specify a
769       character-set explicitly.
770
771          my $body = Mail::Box::Body::Lines->new(data => \@lines);
772          # now mime=text/plain, charset=PERL
773
774          my $msg  = Mail::Message->buildFromBody($body);
775          $msg->body($body);
776          $msg->attach($body);   # etc
777          # these all will convert the charset=PERL into real utf-8
778

DIAGNOSTICS

780       Warning: Charset $name is not known
781           The encoding or decoding of a message body encounters a character
782           set which is not understood by Perl's Encode module.
783
784       Warning: No decoder defined for transfer encoding $name.
785           The data (message body) is encoded in a way which is not currently
786           understood, therefore no decoding (or recoding) can take place.
787
788       Warning: No encoder defined for transfer encoding $name.
789           The data (message body) has been decoded, but the required encoding
790           is unknown.  The decoded data is returned.
791
792       Error: Package $package does not implement $method.
793           Fatal error: the specific package (or one of its superclasses) does
794           not implement this method where it should. This message means that
795           some other related classes do implement this method however the
796           class at hand does not.  Probably you should investigate this and
797           probably inform the author of the package.
798
799       Warning: Unknown line terminator $eol ignored
800

SEE ALSO

802       This module is part of Mail-Message distribution version 3.009, built
803       on February 07, 2020. Website: http://perl.overmeer.net/CPAN/
804

LICENSE

806       Copyrights 2001-2020 by [Mark Overmeer <markov@cpan.org>]. For other
807       contributors see ChangeLog.
808
809       This program is free software; you can redistribute it and/or modify it
810       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
811
812
813
814perl v5.32.0                      2020-07-28            Mail::Message::Body(3)
Impressum