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 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 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 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.