NAME
MIME::Tools::overview - an overview of the MIME-tools classes and features
SYNOPSIS
This is part of the MIME-tools documentation. See MIME::Tools for the full table of contents.
DESCRIPTION
This document is an overview of the MIME-tools distribution: how things are put together, what the various classes are for, etc.
Example code
Here's some pretty basic code for parsing a MIME message, and outputting its decoded components to a given directory:
use MIME::Parser;
### Create parser, and set some parsing options:
my $parser = new MIME::Parser;
$parser->output_under("$ENV{HOME}/mimemail");
### Parse input:
$entity = $parser->parse(\*STDIN) or die "parse failed\n";
### Take a look at the top-level entity (and any parts it has):
$entity->dump_skeleton;Here's some code which composes and sends a MIME message containing three parts: a text file, an attached GIF, and some more text:
use MIME::Entity;
### Create the top-level, and set up the mail headers:
$top = MIME::Entity->build(Type =>"multipart/mixed",
From => "me\@myhost.com",
To => "you\@yourhost.com",
Subject => "Hello, nurse!");
### Part #1: a simple text document:
$top->attach(Path=>"./testin/short.txt");
### Part #2: a GIF file:
$top->attach(Path => "./docs/mime-sm.gif",
Type => "image/gif",
Encoding => "base64");
### Part #3: some literal text:
$top->attach(Data=>$message);
### Send it:
open MAIL, "| /usr/lib/sendmail -t -oi -oem" or die "open: $!";
$top->print(\*MAIL);
close MAIL;For more examples, look at the scripts in the examples directory of the MIME-tools distribution.
Classes in the toolkit
Here are the classes you'll generally be dealing with directly:
(START HERE) results() .-----------------.
\ .-------->| MIME:: |
.-----------. / | Parser::Results |
| MIME:: |--' `-----------------'
| Parser |--. .-----------------.
`-----------' \ filer() | MIME:: |
| parse() `-------->| Parser::Filer |
| gives you `-----------------'
| a... | output_path()
| | determines
| | path() of...
| head() .--------. |
| returns... | MIME:: | get() |
V .-------->| Head | etc... |
.--------./ `--------' |
.---> | MIME:: | |
`-----| Entity | .--------. |
parts() `--------'\ | MIME:: | /
returns `-------->| Body |<---------'
sub-entities bodyhandle() `--------'
(if any) returns... | open()
| returns...
|
V
.--------. read()
| IO:: | getline()
| Handle | print()
`--------' etc...To illustrate, parsing works this way:
The "parser" parses the MIME stream. A parser is an instance of
MIME::Parser. You hand it an input stream (like a filehandle) to parse a message from: if the parse is successful, the result is an "entity".A parsed message is represented by an "entity". An entity is an instance of
MIME::Entity(a subclass ofMail::Internet). If the message had "parts" (e.g., attachments), then those parts are "entities" as well, contained inside the top-level entity. Each entity has a "head" and a "body".The entity's "head" contains information about the message. A "head" is an instance of
MIME::Head(a subclass ofMail::Header). It contains information from the message header: content type, sender, subject line, etc.The entity's "body" knows where the message data is. You can ask to "open" this data source for reading or writing, and you will get back an "I/O handle".
You can open() a "body" and get an "I/O handle" to read/write message data. This handle is an object that is basically like an IO::Handle or a FileHandle... it can be any class, so long as it supports a small, standard set of methods for reading from or writing to the underlying data source.
A typical multipart message containing two parts -- a textual greeting and an "attached" GIF file -- would be a tree of MIME::Entity objects, each of which would have its own MIME::Head. Like this:
.--------.
| MIME:: | Content-type: multipart/mixed
| Entity | Subject: Happy Samhaine!
`--------'
|
`----.
parts |
| .--------.
|---| MIME:: | Content-type: text/plain; charset=us-ascii
| | Entity | Content-transfer-encoding: 7bit
| `--------'
| .--------.
|---| MIME:: | Content-type: image/gif
| Entity | Content-transfer-encoding: base64
`--------' Content-disposition: inline;
filename="hs.gif"Toolkit configuration
If you want to tweak the way this toolkit works (for example, to turn on debugging), use the routines in the MIME::Tools module.
MIME::Tools->debugging($bool); ### turn all debugging on?
MIME::Tools->quiet($bool); ### suppress warnings?Parsing messages
You usually start by creating an instance of MIME::Parser and setting up certain parsing parameters: what directory to save extracted files to, how to name the files, etc.
You then give that instance a readable filehandle on which waits a MIME message. If all goes well, you will get back a MIME::Entity object (a subclass of Mail::Internet), which consists of...
A MIME::Head (a subclass of Mail::Header) which holds the MIME header data.
A MIME::Body, which is a object that knows where the body data is. You ask this object to "open" itself for reading, and it will hand you back an "I/O handle" for reading the data: this is a FileHandle-like object, and could be of any class, so long as it conforms to a subset of the IO::Handle interface.
If the original message was a multipart document, the MIME::Entity object will have a non-empty list of "parts", each of which is in turn a MIME::Entity (which might also be a multipart entity, etc, etc...).
Internally, the parser (in MIME::Parser) asks for instances of MIME::Decoder whenever it needs to decode an encoded file. MIME::Decoder has a mapping from supported encodings (e.g., 'base64') to classes whose instances can decode them. You can add to this mapping to try out new/experiment encodings. You can also use MIME::Decoder by itself.
Composing messages
All message composition is done via the MIME::Entity class. For single-part messages, you can use the MIME::Entity/build constructor to create MIME entities very easily.
For multipart messages, you can start by creating a top-level multipart entity with MIME::Entity::build(), and then use the similar MIME::Entity::attach() method to attach parts to that message. Please note: what most people think of as "a text message with an attached GIF file" is really a multipart message with 2 parts: the first being the text message, and the second being the GIF file.
When building MIME a entity, you'll have to provide two very important pieces of information: the content type and the content transfer encoding. The type is usually easy, as it is directly determined by the file format; e.g., an HTML file is text/html. The encoding, however, is trickier... for example, some HTML files are 7bit-compliant, but others might have very long lines and would need to be sent quoted-printable for reliability.
See the section on encoding/decoding for more details, as well as "A MIME PRIMER".
Sending email
Since MIME::Entity inherits directly from Mail::Internet, you can use the normal Mail::Internet mechanisms to send email. For example,
$entity->smtpsend;Encoding/decoding support
The MIME::Decoder class can be used to encode as well; this is done when printing MIME entities. All the standard encodings are supported (see "A MIME PRIMER" for details):
Encoding: | Normally used when message contents are:
-------------------------------------------------------------------
7bit | 7-bit data with under 1000 chars/line, or multipart.
8bit | 8-bit data with under 1000 chars/line.
binary | 8-bit data with some long lines (or no line breaks).
quoted-printable | Text files with some 8-bit chars (e.g., Latin-1 text).
base64 | Binary files.Which encoding you choose for a given document depends largely on (1) what you know about the document's contents (text vs binary), and (2) whether you need the resulting message to have a reliable encoding for 7-bit Internet email transport.
In general, only quoted-printable and base64 guarantee reliable transport of all data; the other three "no-encoding" encodings simply pass the data through, and are only reliable if that data is 7bit ASCII with under 1000 characters per line, and has no conflicts with the multipart boundaries.
I've considered making it so that the content-type and encoding can be automatically inferred from the file's path, but that seems to be asking for trouble... or at least, for Mail::Cap...
SEE ALSO
See "SYNOPSIS" in MIME::Tools for the full table of contents.