NAME

    MIME-tools - modules for parsing (and creating!) MIME entities

SYNOPSIS

    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 the output directory:
        my $parser = new MIME::Parser;
        $parser->output_dir("$ENV{HOME}/mimemail");
         
        # Parse input:
        $entity = $parser->read(\*STDIN) or die "couldn't parse MIME stream";
        
        # 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 = build MIME::Entity Type   =>"multipart/mixed",
                                  -From    => "me\@myhost.com",
                                  -To      => "you\@yourhost.com",
                                  -Subject => "Hello, nurse!";
        
        # Attachment #1: a simple text document: 
        attach $top  Path=>"./testin/short.txt";
        
        # Attachment #2: a GIF file:
        attach $top  Path        => "./docs/mime-sm.gif",
                     Type        => "image/gif",
                     Encoding    => "base64";
            
        # Attachment #3: some literal text:
        attach $top  Data=>$message;
        
        # Send it:
        open MAIL, "| /usr/lib/sendmail -t -i" or die "open: $!";
        $top->print(\*MAIL);
        close MAIL;


DESCRIPTION

    MIME-tools is a collection of Perl5 MIME:: modules for parsing,
    decoding, *and generating* single- or multipart (even nested multipart)
    MIME messages. (Yes, kids, that means you can send messages with
    attached GIF files).

CONTENTS

  Modules in this toolkit

        Module       DSLI   Description                                  Info
        ----------   ----   ------------------------------------------   ----
        MIME::
        ::Body       adpO   Abstract message holder (file, scalar, etc.) ERYQ
        ::Decoder    bdpO   OO interface for decoding MIME messages      ERYQ
        ::Entity     bdpO   An extracted and decoded MIME entity         ERYQ
        ::Field::*   bdpO   Mail::Field subclasses for parsing fields    ERYQ
        ::Head       bdpO   A parsed MIME header (Mail::Header subclass) ERYQ
        ::IO         adpO   Simple I/O handles for filehandles/scalars   ERYQ
        ::Latin1     adpO   Encoding 8-bit Latin-1 as 7-bit ASCII        ERYQ
        ::Parser     bdpO   Parses streams to create MIME entities       ERYQ
        ::ParserBase bdpO   For building your own MIME parser            ERYQ
        ::ToolUtils  adpO   For tweaking the MIME-tools library          ERYQ


  Programs in this toolkit

        mimedump    - dump out a summary of the contents of a MIME message
        mimeexplode - parse/decode a MIME message into its component files
        mimesend    - send a message with attachments from the command line


REQUIREMENTS

    You'll need Perl5.002 or better.

    You'll need to obtain and install the following kits from the CPAN:

    MIME::(QuotedPrint, Base64)
        These perform the low-level MIME decoding. Get these from Gisle Aas'
        author directory. They are also reported to be in the LWP
        distribution.

    MailTools (1.06 or higher)
        This is Graham Barr's revamped set of Mail:: modules. Many of them
        are now superclasses of the MIME:: modules, and perform the core
        functionality of manipulating headers and fields.


    For your convenience, possibly-old copies of the MIME:: modules are
    provided in the ./etc directory, of the distribution, but they are NOT
    installed for you during the installation procedure.

CHANGES

  Version 2.13

    New features
        Added RFC-1522-style decoding of encoded header fields. Header
        decoding can now be done automatically during parsing via the new
        `decode()' method in MIME::Head... just tell your parser object that
        you want to `decode_headers()'. I<Thanks to Kent Boortz for
        providing the idea, and the baseline RFC-1522-decoding code!>

        Building MIME messages is even easier. Now, when you use
        MIME::Entity's `build()' or `attach()', you can also supply
        individual mail headers to set (e.g., `-Subject', `-From', `-To').

        Added `Disposition' to MIME::Entity's `build()' method. *Thanks to
        Kurt Freytag for suggesting this feature.*

        An `X-Mailer' header is now output by default in all MIME-Entity-
        prepared messages, so any bad MIME we generate can be traced back to
        this toolkit.

        Added `purge()' method to MIME::Entity for deleteing leftover files.
        *Thanks to Jason L. Tibbitts III for suggesting this feature.*

        Added `seek()' and `tell()' methods to built-in MIME::IO classes.
        Only guaranteed to work when reading! *Thanks to Jason L. Tibbitts
        III for suggesting this feature.*

        When parsing a multipart message with apparently no boundaries, the
        error message you get has been improved. *Thanks to Andreas Koenig
        for suggesting this.*

    Bug fixes
        B<Patched over a Perl 5.002 (and maybe earlier and later) bug
        involving FileHandle::new_tmpfile.> It seems that the underlying
        filehandles were not being closed when the FileHandle objects went
        out of scope! There is now an internal routine that creates true
        FileHandle objects for anonymous temp files. I<Thanks to Dragomir R.
        Radev and Zyx for reporting the weird behavior that led to the
        discovery of this bug.>

        MIME::Entity's `build()' method now warns you if you give it an
        illegal boundary string, and substitutes one of its own.

        MIME::Entity's `build()' method now generates safer, fully-RFC-1521-
        compliant boundary strings.

        Bug in MIME::Decoder's `install()' method was fixed. *Thanks to Rolf
        Nelson and Nickolay Saukh for finding this.*

        Changed FileHandle::new_tmpfile to FileHandle->new_tmpfile, so some
        Perl installations will be happier. *Thanks to Larry W. Virden for
        finding this bug.*

        Gave `=over' an arg of 4 in all PODs. *Thanks to Larry W. Virden for
        pointing out the problems of bare =over's*


SUPPORT

    Please email me directly with questions/problems (see AUTHOR below).

AUTHOR

    MIME-tools was created by:

        ___  _ _ _   _  ___ _     
       / _ \| '_| | | |/ _ ' /    Eryq
      |  __/| | | |_| | |_| |     http://www.mcs.net/~eryq
       \___||_|  \__, |\__, |__   eryq@enteract.com
                 |___/    |___/   eryq@rhine.gsfc.nasa.gov 


    Initial release (1.0): 28 April 1996. Re-release (2.0): Halloween 1996.

