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 of Mail::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 of Mail::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.

cpanm MIME::Head

perl -MCPAN -e shell
install MIME::Head