This module is ALPHA code, which means that public interfaces are largely untested, and may change in future releases. Use with caution! Please report any errors back to eryq@zeegee.com as soon as you can.
MIME::Parser - experimental class for parsing MIME streams
### Create a new parser object: my $parser = new MIME::Parser; ### Tell it where to put things: $parser->output_under("/tmp"); ### Parse an input filehandle: $entity = $parser->parse(\*STDIN); ### Congratulations: you now have a (possibly multipart) MIME entity! $entity->dump_skeleton; # for debugging
### Parse from filehandles: $entity = $parser->parse(\*STDIN); $entity = $parser->parse(IO::File->new("some command|"); ### Parse from any object that supports getline() and read(): $entity = $parser->parse($myHandle); ### Parse an in-core MIME message: $entity = $parser->parse_data($message); ### Parse an MIME message in a file: $entity = $parser->parse_open("/some/file.msg"); ### Parse an MIME message out of a pipeline: $entity = $parser->parse_open("gunzip - < file.msg.gz |"); ### Parse already-split input (as "deliver" would give it to you): $entity = $parser->parse_two("msg.head", "msg.body");
### Keep parsed message components in core (default outputs to disk): $parser->output_to_core(1); ### Output each message's components to a one-per-message directory: $parser->output_under("/tmp"); ### Output each message's components to the same directory: $parser->output_dir("/tmp"); ### Change how nameless message-component files are named: $parser->output_prefix("msg");
### Normal mechanism: eval { $entity = $parser->parse(\*STDIN) }; if ($@) { $results = $parser->results; $decapitated = $parser->last_head; ### get last top-level head } ### Ultra-tolerant mechanism: $parser->ignore_errors(1); $entity = eval { $parser->parse(\*STDIN) }; $error = ($@ || $parser->last_error);
### Automatically attempt to RFC-1522-decode the MIME headers: $parser->decode_headers(1); ### Parse contained "message/rfc822" objects as nested MIME streams? $parser->extract_nested_messages('REPLACE'); ### Forgive a lot of normally-fatal errors: $parser->ignore_errors;
### Convert a Mail::Internet object to a MIME::Entity: @lines = (@{$mail->header}, "\n", @{$mail->body}); $entity = $parser->parse_data(\@lines);
You can inherit from this class to create your own subclasses that parse MIME streams into MIME::Entity objects.
my $parser = new MIME::Parser; $parser->output_dir("/tmp"); $parser->output_prefix("msg1"); my $entity = $parser->parse(\*STDIN);
Any arguments are passed into init()
.
Don't override this in your subclasses; override init() instead.
If YESNO is true, decoding is done. If YESNO is false (the default), no attempt at decoding will be done. With no argument, just returns the current setting.
message/rfc822
:
literally, the text of an embedded mail/news/whatever message.
This option controls whether (and how) we parse that embedded message.
If the OPTION is false, we treat such a message just as if it were a
text/plain
document, without attempting to decode its contents.
If the OPTION is true (the default), the body of the message/rfc822
part is parsed by this parser, creating an entity object.
What happens then is determined by the actual OPTION:
message/rfc822
entity (as if the containing message were a special kind of
"multipart" message).
You can recover the sub-entity by invoking the parts()
method on the message/rfc822
entity.
message/rfc822
entity, as though
the message/rfc822
"container" never existed.
Warning: notice that, with this option, all the header information
in the message/rfc822
header is lost. This might seriously bother
you if you're dealing with a top-level message, and you've just lost
the sender's address and the subject line. :-/
.
Thanks to Andreas Koenig for suggesting this method.
If YESNO is true (the default), many syntax errors are tolerated. If YESNO is false, fatal errors throw exceptions. With no argument, just returns the current setting.
A scalar which holds the message.
A ref to a scalar which holds the message. This is an efficiency hack.
A ref to an array of scalars. They are treated as a stream which (conceptually) consists of simply concatenating the scalars.
Returns the parsed MIME::Entity on success. Throws exception on failure.
The INSTREAM can be given as a readable FileHandle, an IO::File,
a globref filehandle (like \*STDIN
),
or as any blessed object conforming to the IO:: interface
(which minimally implements getline() and read()).
Returns the parsed MIME::Entity on success. Throws exception on failure.
parse()
.
Simply give this method any expression that may be sent as the second
argument to open() to open a filehandle for reading.
Returns the parsed MIME::Entity on success. Throws exception on failure.
parse_open()
, intended for programs
running under mail-handlers like deliver, which splits the incoming
mail message into a header file and a body file.
Simply give this method the paths to the respective files.
Warning: it is assumed that, once the files are cat'ed together, there will be a blank line separating the head part and the body part.
Warning: new implementation slurps files into line array for portability, instead of using 'cat'. May be an issue if your messages are large.
Returns the parsed MIME::Entity on success. Throws exception on failure.
"/"
characters,
or if it's "."
, ".."
, or empty.
Override this method in a subclass if you just want to change which externally-provided filenames are allowed, and which are not. Like this:
package MIME::MyParser; use MIME::Parser; @ISA = qw(MIME::Parser); sub evil_filename { my ($self, $name) = @_; return ($name !~ /^[a-z\d][a-z\d\._-]*$/i); }
Note: This method used to be a lot stricter, but it unnecessailry inconvenienced users on non-ASCII systems. That has been changed in 4.x.
Thanks to Andrew Pimlott for finding a real dumb bug in the original version. Thanks to Nickolay Saukh for noting that evil is in the eye of the beholder.
"."
.
If DIRECTORY
is not given, the current output directory is returned.
If DIRECTORY
is given, the output directory is set to the new value,
and the previous value is returned.
Note: this is used by the output_path()
method in this class.
It should also be used by subclasses, but if a subclass decides to
output parts in some completely different manner, this method may
of course be completely ignored.
The output_dir() will return the path to this message-specific directory until the next parse is begun, so you can do this:
use File::Path; $parser->output_under("/tmp"); $ent = eval { $parser->parse_open($msg); }; ### parse if (!$ent) { ### parse failed rmtree($parser->output_dir); die "parse failed: $@"; } else { ### parse succeeded ...do stuff... }
With no argument, returns the current BASEDIR.
output_dir()
,
and the "filename" portion will be determined as follows:
If the MIME header contains a recommended filename, and it is not judged to be "evil" (evil filenames are ones which contain things like "/" or ".." or non-ASCII characters), then that filename will be used.
If the MIME header contains a recommended filename, but it is judged to be "evil", then a warning is issued and we pretend that there was no recommended filename. In which case...
If the MIME header does not specify a recommended filename, then
a simple temporary file name, starting with the output_prefix()
,
will be used.
Note: If you don't like the behavior of this function, you can define your own subclass of MIME::Parser and override it there:
package MIME::MyParser; require 5.002; ### for SUPER use package MIME::Parser; @MIME::MyParser::ISA = qw(MIME::Parser); sub output_path { my ($self, $head) = @_; ### Your code here; FOR EXAMPLE... if (i_have_a_preference) { return my_custom_path; } else { ### return the default path: return $self->SUPER::output_path($head); } } 1;
Note: Nickolay Saukh pointed out that, given the subjective nature of what is "evil", this function really shouldn't warn about an evil filename, but maybe just issue a debug message. I considered that, but then I thought: if debugging were off, people wouldn't know why (or even if) a given filename had been ignored. In mail robots that depend on externally-provided filenames, this could cause hard-to-diagnose problems. So, the message is still a warning, but now it's only output if $^W is true.
Thanks to Laurent Amon for pointing out problems with the original implementation, and for making some good suggestions. Thanks also to Achim Bohnet for pointing out that there should be a hookless, OO way of overriding the output_path.
If PREFIX is not given, the current output prefix is returned. If PREFIX is given, the output directory is set to the new value, and the previous value is returned.
If YESNO is false (the default), then all body data goes to disk files.
If YESNO is true, then all body data goes to in-core data structures This is a little risky (what if someone emails you an MPEG or a tar file, hmmm?) but people seem to want this bit of noose-shaped rope, so I'm providing it. Note that setting this attribute true does not mean that parser-internal temporary files are avoided! Use tmp_to_core() for that.
With no argument, returns the current setting as a boolean.
If YESNO is true (the default), we allow recycling; tmpfiles persist until the parser itself is destroyed. If YESNO is false, we do not allow recycling; tmpfiles persist only as long as they are needed during the parse. With no argument, just returns the current setting.
If YESNO is true, we implement new_tmpfile() via in-core handles. If YESNO is false (the default), we use real tmpfiles. With no argument, just returns the current setting.
If YESNO is false (the default), then we will not use IO::InnerFile. If YESNO is true, we use IO::InnerFile if we can. With no argument, just returns the current setting.
Note: inner files are slower than real tmpfiles, but possibly faster than in-core tmpfiles... so your choice for this option will probably depend on your choice for tmp_to_core() and the kind of input streams you are parsing.
If so, then this is the method that your subclass should invoke during init. Use it like this:
package MyParser; @ISA = qw(MIME::Parser); ... sub init { my $self = shift; $self->SUPER::init(@_); ### do my parent's init $self->interface(ENTITY_CLASS => 'MIME::MyEntity'); $self->interface(HEAD_CLASS => 'MIME::MyHead'); $self; ### return }
With no VALUE, returns the VALUE currently associated with that ROLE.
If you set the output_to_core
option to false before parsing
(the default), then we examine the HEAD for a recommended
filename (generating a random one if none is available),
and create a new MIME::Body::File on that filename in the parser's
current output_dir()
.
If you set the output_to_core
option to true before parsing,
then you get a MIME::Body::InCore instead.
If you want the parser to do something else entirely, you can override this method in a subclass.
If you do override this, make certain that the object you return is set for binmode(), and is able to handle the following methods:
read(BUF, NBYTES) getline() getlines() print(@ARGS) flush() seek(0, 0)
Fatal exception if the stream could not be established.
If RECYCLE is given, it is an object returned by a previous invocation of this method; to recycle it, this method must effectively rewind and truncate it, and return the same object. If you don't want to support recycling, just ignore it and always return a new object.
### Parse an input stream: eval { $entity = $parser->parse(\*STDIN) }; if (!$entity) { ### parse failed! my $decapitated = $parser->last_head; ... }
Optimum input mechanisms:
parse() YES (if you give it a globref or a subclass of IO::File) parse_open() YES parse_data() NO (see below) parse_two() NO (see below) Optimum settings:
decode_headers() *** (no real difference; 0 is slightly faster) extract_nested_messages() 0 (may be slightly faster, but in general you want it set to 1) output_to_core() 0 (will be MUCH faster) tmp_recycling() 1? (probably, but should be investigated) tmp_to_core() 0 (will be MUCH faster) use_inner_files() 0 (if tmp_to_core() is 0; use 1 otherwise)
File I/O is much faster than in-core I/O. Although it seems like slurping a message into core and processing it in-core should be faster... it isn't. Reason: Perl's filehandle-based I/O translates directly into native operating-system calls, whereas the in-core I/O is implemented in Perl.
Inner files are slower than real tmpfiles, but faster than in-core ones. If speed is your concern, that's why you should set use_inner_files(true) if you set tmp_to_core(true): so that we can bypass the slow in-core tmpfiles if the input stream permits.
Native I/O is much faster than object-oriented I/O. It's much faster to use <$foo> than $foo->getline. For backwards compatibilty, this module must continue to use object-oriented I/O in most places, but if you use parse() with a "real" filehandle (string, globref, or subclass of IO::File) then MIME::Parser is able to perform some crucial optimizations.
The parse_two() call is very inefficient. Currently this is just a front-end onto parse_data(). If your OS supports it, you're far better off doing something like:
$parser->parse_open("/bin/cat msg.head msg.body |");
Optimum input mechanisms:
parse() YES parse_open() YES parse_data() NO (in-core I/O will burn core) parse_two() NO (in-core I/O will burn core) Optimum settings:
decode_headers() *** (no real difference) extract_nested_messages() *** (no real difference) output_to_core() 0 (will use MUCH less memory) tmp_recycling() 0? (promotes faster GC if tmp_to_core is 1) tmp_to_core() 0 (will use MUCH less memory) use_inner_files() *** (no real difference, but set it to 1 if you *must* have tmp_to_core set to 1, so that you avoid in-core tmpfiles)
Optimum input mechanisms:
parse() *** (doesn't matter) parse_open() *** (doesn't matter) parse_data() *** (doesn't matter) parse_two() *** (doesn't matter) Optimum settings:
decode_headers() 0 (sidesteps problem of bad hdr encodings) extract_nested_messages() 0 (sidesteps problems of bad nested messages, but often you want it set to 1 anyway). output_to_core() *** (doesn't matter) tmp_recycling() *** (doesn't matter) tmp_to_core() *** (doesn't matter) use_inner_files() *** (doesn't matter)
Optimum input mechanisms:
parse() YES (if you give it a seekable handle) parse_open() YES (becomes a seekable handle) parse_data() NO (unless you set tmp_to_core(1)) parse_two() NO (unless you set tmp_to_core(1)) Optimum settings:
decode_headers() *** (doesn't matter) extract_nested_messages() *** (doesn't matter) output_to_core() *** (doesn't matter) tmp_recycling 1 (restricts created files to 1 per parser) tmp_to_core() 1 use_inner_files() 1
If we can use them, inner files avoid most tmpfiles.`< If you parse from a seekable-and-tellable filehandle, then the internal process_to_bound() doesn't need to extract each part into a temporary buffer; it can use IO::InnerFile (warning: this will slow down the parsing of messages with large attachments).
You can veto tmpfiles entirely. If you might not be parsing from a seekable-and-tellable filehandle, you can set tmp_to_core() true: this will always use in-core I/O for the buffering (warning: this will slow down the parsing of messages with large attachments).
Final resort. You can always override new_tmpfile() in a subclass.
A better solution for this case would be to set up some form of state machine for input processing. This will be left for future versions.
The revised implementation uses a temporary file (a la tmpfile()
)
during parsing to hold the encoded portion of the current MIME
document or part. This file is deleted automatically after the
current part is decoded and the data is written to the "body stream"
object; you'll never see it, and should never need to worry about it.
Some folks have asked for the ability to bypass this temp-file mechanism, I suppose because they assume it would slow down their application. I considered accomodating this wish, but the temp-file approach solves a lot of thorny problems in parsing, and it also protects against hidden bugs in user applications (what if you've directed the encoded part into a scalar, and someone unexpectedly sends you a 6 MB tar file?). Finally, I'm just not conviced that the temp-file use adds significant overhead.
"\r\n"
). However, it is extremely likely that folks will want to
parse MIME streams where each line ends in the local newline
character "\n"
instead.
An attempt has been made to allow the parser to handle both CRLF and newline-terminated input.
"7bit"
and "8bit"
decoders will decode both
a "\n"
and a "\r\n"
end-of-line sequence into a "\n"
.
The "binary"
decoder (default if no encoding specified)
still outputs stuff verbatim... so a MIME message with CRLFs
and no explicit encoding will be output as a text file
that, on many systems, will have an annoying ^M at the end of
each line... but this is as it should be.
If your mailer creates multipart boundary strings that contain newlines when they appear in the message body, give it two weeks notice and find another one. If your mail robot receives MIME mail like this, regard it as syntactically incorrect MIME, which it is.
Why do I say that? Well, in RFC-1521, the syntax of a boundary is given quite clearly:
boundary := 0*69<bchars> bcharsnospace bchars := bcharsnospace / " " bcharsnospace := DIGIT / ALPHA / "'" / "(" / ")" / "+" /"_" / "," / "-" / "." / "/" / ":" / "=" / "?"
All of which means that a valid boundary string cannot have newlines in it, and any newlines in such a string in the message header are expected to be solely the result of folding the string (i.e., inserting to-be-removed newlines for readability and line-shortening only).
Yet, there is at least one brain-damaged user agent out there that composes mail like this:
MIME-Version: 1.0 Content-type: multipart/mixed; boundary="----ABC- 123----" Subject: Hi... I'm a dork! This is a multipart MIME message (yeah, right...) ----ABC- 123---- Hi there!
We have got to discourage practices like this (and the recent file upload idiocy where binary files that are part of a multipart MIME message aren't base64-encoded) if we want MIME to stay relatively simple, and MIME parsers to be relatively robust.
Thanks to Andreas Koenig for bringing a baaaaaaaaad user agent to my attention.
Eryq (
All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
$Revision: 5.203 $ $Date: 2000/06/06 04:35:13 $