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.204 Bug in MIME::Head::original_text fixed. Well, it took a while, but another bug surfaced from my transition from 1.x to 2.x. This method was, quite idiotically, sorting the header fields. *Thanks, as usual, to Andreas Koenig for spotting this one.* MIME::ParserBase no longer defaults to RFC-1522-decoding headers. The documentation correctly stated that the default setting was to *not* RFC-1522-decode the headers. The code, on the other hand, was init'ing this parser option in the "on" position. This has been fixed. MIME::ParserBase::parse_nested_messages reexamined. If you use this feature, please re-read the documentation. It explains a little more precisely what the ramifications are. MIME::Entity tries harder to ensure MIME compliance. It is now a fatal error to use certain bad combinations of content type and encoding when "building", or to attempt to "attach" to anything that is not a multipart document. My apologies if this inconveniences anyone, but it was just too darn easy before for folks to create bad MIME, and gosh darn it, good libraries should at least *try* to protect you from mistakes. The "make" now halts if you don't have the right stuff, provided your MakeMaker supports PREREQ_PM. See the the section on "REQUIREMENTS" section for what you need to install this package. I still provide old courtesy copies of the MIME:: decoding modules. *Thanks to Hugo van der Sanden for suggesting this.* The "make test" is far less chatty. Okay, okay, STDERR is evil. Now a `"make test"' will just give you the important stuff: do a `"make test TEST_VERBOSE=1"' if you want the gory details (advisable if sending me a bug report). *Thanks to Andreas Koenig for suggesting this.* SUPPORT Please email me directly with questions/problems (see AUTHOR below). If you want to be placed on an email distribution list (not a mailing list!) for MIME-tools, and receive bug reports, patches, and updates as to when new MIME-tools releases are planned, just email me and say so. If your project is using MIME-tools, it might not be a bad idea to find out about those bugs *before* they become problems... 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.