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 3.203

    No, there haven't been any major changes between 2.x and 3.x. The major-
    version increase was from a few more tweaks to get $VERSION to be
    calculated better and more efficiently (I had been using RCS version
    numbers in a way which created problems for users of CPAN::). After a
    couple of false starts, all modules have been upgraded to RCS 3.201 or
    higher.

    You can now parse a MIME message from a scalar, an array-of-scalars, or
    any MIME::IO-compliant object (including IO:: objects.) Take a look at
    parse_data() in MIME::ParserBase. The parser code has been modified to
    support the MIME::IO interface. *Thanks to fellow Chicagoan Tim Pierce
    (and countless others) for asking.*

    More sensible toolkit configuration. A new config() method in
    MIME::ToolUtils makes a lot of toolkit-wide configuration cleaner. Your
    old calls will still work, but with deprecation warnings.

    You can now sign messages just like in Mail::Internet. See MIME::Entity
    for the interface.

    You can now remove signatures from messages just like in Mail::Internet.
    See MIME::Entity for the interface.

    You can now compute/strip content lengths and other non-standard MIME
    fields. See sync_headers() in MIME::Entity. *Thanks to Tim Pierce for
    bringing the basic problem to my attention.*

    Many warnings are now silent unless $^W is true. That means unless you
    run your Perl with -w, you won't see deprecation warnings, non-fatal-
    error messages, etc. But of course you run with -w, so this doesn't
    affect you. `:-)'

    Completed the 7-bit encodings in MIME::Latin1. We hadn't had complete
    coverage in the conversion from 8- to 7-bit; now we do. *Thanks to Rolf
    Nelson for bringing this to my attention.*

    Fixed broken parse_two() in MIME::ParserBase. BTW, if your code worked
    with the "broken" code, it should *still* work. *Thanks again to Tim
    Pierce for bringing this to my attention.*

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.