perldoc > Mail::Message::Body::Encode

man perldoc info pydoc3 ri search

📜 NAME

Mail::Message::Body::Encode - organize general message encodings

🚀 Quick Reference

Use Case	Command	Description
Decode message body	$msg->decoded	Decode the message body to a usable format
Encode message body	$body->encode(transfer_encoding => '7bit')	Encode body with specified transfer encoding
Check body validity	$body->check()	Remove illegal characters from body
Test if binary	$body->isBinary()	Returns true if un-encoded body is binary
Test if text	$body->isText()	Returns true if un-encoded body is text
Unify body types	$body->unify($other)	Make two bodies compatible for comparison

🔍 SYNOPSIS

 my <a href="/phpMan.php/perldoc/Mail::Message">Mail::Message</a> $msg = ...;
 my $decoded = $msg->decoded;
 my $encoded = $msg->encode(mime_type => 'image/gif',
     transfer_encoding => 'base64');

 my $body = $msg->body;
 my $decoded = $body->decoded;
 my $encoded = $body->encode(transfer_encoding => '7bit');

📖 DESCRIPTION

Manages the message's body encodings and decodings on request of the main program. This package adds functionality to the Mail::Message::Body class when the decoded() or encode() method is called.

Four types of encodings are handled (in the right order):

• 🔹 eol encoding – Various operating systems use different line endings (LF, CR, CR/LF). Internet messages always use CRLF.
• 🔹 transfer encoding – Binary/non-ASCII data must be encoded to plain ASCII for transmission. Implemented in Mail::Message::TransferEnc.
• 🔹 mime-type translation – NOT IMPLEMENTED YET
• 🔹 charset conversion

⚙️ METHODS

🛠️ Constructing a body

• $obj->check() – Check the content of the body not to include illegal characters. Returns a checked body, a new object, or undef if the decoder is not defined.
• $obj->encode(%options) – Encode (translate) a Mail::Message::Body into a different format. See DESCRIPTION above. Options not specified will not trigger conversions.
  • -Option – charset, mime_type, result_type, transfer_encoding
  • charset => CODESET|'PERL' – If CODESET is specified, data is raw bytes; if 'PERL', it's internal character representation.
  • mime_type => STRING|FIELD – Convert to specified mime type. FIELD is a Mail::Message::Field.
  • result_type => CLASS – Class of body to create for re-coding. Must extend Mail::Message::Body.
  • transfer_encoding => STRING|FIELD
• $obj->encoded() – Encode the body to a format acceptable for transmission or storage. Returns the body if already prepared, or a new encoded body otherwise.
• $obj->unify($body) – Unify the type of the given $body with the called body. Returns undef if impossible. Example:

   my $bodytype = <a href="/phpMan.php/perldoc/Mail::Message::Body::Lines">Mail::Message::Body::Lines</a>;
   my $html  = $bodytype->new(mime_type=>'text/html', data => []);
   my $plain = $bodytype->new(mime_type=>'text/plain', ...);
  
   my $unified = $html->unify($plain);
   # $unified is the data of plain translated to html (if possible).

📦 About the payload

• $obj->dispositionFilename( [$directory] ) – Searches for "filename" and "name" attributes. Without $directory, returns the name unmodified. With $directory, composes a filename (safe basename). If no name found or already in use, generates a unique name. See RFC6266 section 4.3 for security aspects.
• $obj->isBinary() – Returns true when the un-encoded message is binary data (from MIME::Types).
• $obj->isText() – Returns true when the un-encoded message contains printable text.

🔧 Internals

• $obj->addTransferEncHandler( $name, <$class|$object> )
Mail::Message::Body->addTransferEncHandler( $name, <$class|$object> ) – Relate the named transfer encoding to an object or class. The class/object must extend Mail::Message::TransferEnc. Replaces existing handler for that name.
• $obj->getTransferEncHandler($type) – Get the transfer encoder/decoder for $type, or undef if none.

⚠️ DIAGNOSTICS

• Warning: Charset $name is not known – The encoding/decoding encounters a charset not understood by Perl's Encode module.
• Warning: No decoder defined for transfer encoding $name – The data is encoded in an unknown way; no decoding possible.
• Warning: No encoder defined for transfer encoding $name – The data has been decoded, but the required encoding is unknown; decoded data is returned.

📚 SEE ALSO

This module is part of Mail-Message distribution version 3.012, built on February 11, 2022. Website: http://perl.overmeer.net/CPAN/

📄 LICENSE

Copyrights 2001-2022 by [Mark Overmeer <markov AT cpan.org>]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/

📜 NAME 🚀 Quick Reference 🔍 SYNOPSIS 📖 DESCRIPTION ⚙️ METHODS ⚠️ DIAGNOSTICS 📚 SEE ALSO 📄 LICENSE