Basic usage examples

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

Examples of input

    ### 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");

Examples of output control

    ### Keep parsed message bodies in core (default outputs to disk):
    $parser->output_to_core(1);

    ### Output each message body to a one-per-message directory:
    $parser->output_under("/tmp");

    ### Output each message body to the same directory:
    $parser->output_dir("/tmp");

    ### Change how nameless message-component files are named:
    $parser->output_prefix("msg");

    ### Put temporary files somewhere else
    $parser->tmp_dir("/var/tmp/mytmpdir");

Examples of error recovery

    ### 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);

    ### Cleanup all files created by the parse:
    eval { $entity = $parser->parse(\*STDIN) };
    ...
    $parser->filer->purge;

Examples of parser options

    ### Automatically attempt to RFC 2047-decode the MIME headers?
    $parser->decode_headers(1);             ### default is false

    ### Parse contained "message/rfc822" objects as nested MIME streams?
    $parser->extract_nested_messages(0);    ### default is true

    ### Look for uuencode in "text" messages, and extract it?
    $parser->extract_uuencode(1);           ### default is false

    ### Should we forgive normally-fatal errors?
    $parser->ignore_errors(0);              ### default is true

Miscellaneous examples

    ### Convert a Mail::Internet object to a MIME::Entity:
    my $data = join('', (@{$mail->header}, "\n", @{$mail->body}));
    $entity = $parser->parse_data(\$data);

Construction

new ARGS...

Class method. Create a new parser object. Once you do this, you can then set up various parameters before doing the actual parsing. For example:

    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.

init ARGS...

Instance method. Initiallize a new MIME::Parser object. This is automatically sent to a new object; you may want to override it. If you override this, be sure to invoke the inherited method.

init_parse

Instance method. Invoked automatically whenever one of the top-level parse() methods is called, to reset the parser to a "ready" state.

Altering how messages are parsed

decode_headers [YESNO]

Instance method. Controls whether the parser will attempt to decode all the MIME headers (as per RFC 2047) the moment it sees them. This is not advisable for two very important reasons:

   "I_NEED_TO_FIX_THIS"
          Just shut up and do it.  Not recommended.
          Provided only for those who need to keep old scripts functioning.

   "I_KNOW_WHAT_I_AM_DOING"
          Just shut up and do it.  Not recommended.
          Provided for those who REALLY know what they are doing.

extract_nested_messages OPTION

Instance method. Some MIME messages will contain a part of type "message/rfc822" ,"message/partial" or "message/external-body": 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" or "message/partial" part is parsed by this parser, creating an entity object. What happens then is determined by the actual OPTION:

extract_uuencode [YESNO]

Instance method. If set true, then whenever we are confronted with a message whose effective content-type is "text/plain" and whose encoding is 7bit/8bit/binary, we scan the encoded body to see if it contains uuencoded data (generally given away by a "begin XXX" line).

If it does, we explode the uuencoded message into a multipart, where the text before the first "begin XXX" becomes the first part, and all "begin...end" sections following become the subsequent parts. The filename (if given) is accessible through the normal means.

ignore_errors [YESNO]

Instance method. Controls whether the parser will attempt to ignore normally-fatal errors, treating them as warnings and continuing with the parse.

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.

decode_bodies [YESNO]

Instance method. Controls whether the parser should decode entity bodies or not. If this is set to a false value (default is true), all entity bodies will be kept as-is in the original content-transfer encoding.

To prevent double encoding on the output side MIME::Body->is_encoded is set, which tells MIME::Body not to encode the data again, if encoded data was requested. This is in particular useful, when it's important that the content must not be modified, e.g. if you want to calculate OpenPGP signatures from it.

WARNING: the semantics change significantly if you parse MIME messages with this option set, because MIME::Entity resp. MIME::Body *always* see encoded data now, while the default behaviour is working with *decoded* data (and encoding it only if you request it). You need to decode the data yourself, if you want to have it decoded.

So use this option only if you exactly know, what you're doing, and that you're sure, that you really need it.

Parsing an input source

parse_data DATA

Instance method. Parse a MIME message that's already in core. This internally creates an "in memory" filehandle on a Perl scalar value using PerlIO

You may supply the DATA in any of a number of ways...

parse INSTREAM

Instance method. Takes a MIME-stream and splits it into its component entities.

The INSTREAM can be given as 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. If the message contained too many parts (as set by max_parts), returns undef.

parse_open EXPR

Instance method. Convenience front-end onto "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_two HEADFILE, BODYFILE

Instance method. Convenience front-end onto "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.

Specifying output destination

The benefit to this is that the MIME::Parser code won't be confounded with a lot of garbage related to disk output. The drawback is that the way you override the default behavior will change.

For now, all the normal public-interface methods are still provided, but many are only stubs which create or delegate to the underlying MIME::Parser::Filer object.

filer [FILER]

Instance method. Get/set the FILER object used to manage the output of files to disk. This will be some subclass of MIME::Parser::Filer.

output_dir DIRECTORY

Instance method. Causes messages to be filed directly into the given DIRECTORY. It does this by setting the underlying filer() to a new instance of MIME::Parser::FileInto, and passing the arguments into that class' new() method.

Note: Since this method replaces the underlying filer, you must invoke it before doing changing any attributes of the filer, like the output prefix; otherwise those changes will be lost.

output_under BASEDIR, OPTS...

Instance method. Causes messages to be filed directly into subdirectories of the given BASEDIR, one subdirectory per message. It does this by setting the underlying filer() to a new instance of MIME::Parser::FileUnder, and passing the arguments into that class' new() method.

Note: Since this method replaces the underlying filer, you must invoke it before doing changing any attributes of the filer, like the output prefix; otherwise those changes will be lost.

output_path HEAD

Instance method, DEPRECATED. Given a MIME head for a file to be extracted, come up with a good output pathname for the extracted file. Identical to the preferred form:

     $parser->filer->output_path(...args...);
    

We just delegate this to the underlying filer() object.

output_prefix [PREFIX]

Instance method, DEPRECATED. Get/set the short string that all filenames for extracted body-parts will begin with (assuming that there is no better "recommended filename"). Identical to the preferred form:

     $parser->filer->output_prefix(...args...);
    

We just delegate this to the underlying filer() object.

evil_filename NAME

Instance method, DEPRECATED. Identical to the preferred form:

     $parser->filer->evil_filename(...args...);
    

We just delegate this to the underlying filer() object.

max_parts NUM

Instance method. Limits the number of MIME parts we will parse.

Normally, instances of this class parse a message to the bitter end. Messages with many MIME parts can cause excessive memory consumption. If you invoke this method, parsing will abort with a die() if a message contains more than NUM parts.

If NUM is set to -1 (the default), then no maximum limit is enforced.

With no argument, returns the current setting as an integer

output_to_core YESNO

Instance method. Normally, instances of this class output all their decoded body data to disk files (via MIME::Body::File). However, you can change this behaviour by invoking this method before parsing:

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.

tmp_recycling

Instance method, DEPRECATED.

This method is a no-op to preserve the pre-5.421 API.

The tmp_recycling() feature was removed in 5.421 because it had never actually worked. Please update your code to stop using it.

tmp_to_core [YESNO]

Instance method. Should new_tmpfile() create real temp files, or use fake in-core ones? Normally we allow the creation of temporary disk files, since this allows us to handle huge attachments even when core is limited.

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.

use_inner_files [YESNO]

REMOVED.

Instance method.

MIME::Parser no longer supports IO::InnerFile, but this method is retained for backwards compatibility. It does nothing.

The original reasoning for IO::InnerFile was that inner files were faster than "in-core" temp files. At the time, the "in-core" tempfile support was implemented with IO::Scalar from the IO-Stringy distribution, which used the tie() interface to wrap a scalar with the appropriate IO::Handle operations. The penalty for this was fairly hefty, and IO::InnerFile actually was faster.

Nowadays, MIME::Parser uses Perl's built in ability to open a filehandle on an in-memory scalar variable via PerlIO. Benchmarking shows that IO::InnerFile is slightly slower than using in-memory temporary files, and is slightly faster than on-disk temporary files. Both measurements are within a few percent of each other. Since there's no real benefit, and since the IO::InnerFile abuse was fairly hairy and evil ("writes" to it were faked by extending the size of the inner file with the assumption that the only data you'd ever ->print() to it would be the line from the "outer" file, for example) it's been removed.

Specifying classes to be instantiated

interface ROLE,[VALUE]

Instance method. During parsing, the parser normally creates instances of certain classes, like MIME::Entity. However, you may want to create a parser subclass that uses your own experimental head, entity, etc. classes (for example, your "head" class may provide some additional MIME-field-oriented methods).

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.

new_body_for HEAD

Instance method. Based on the HEAD of a part we are parsing, return a new body object (any desirable subclass of MIME::Body) for receiving that part's data.

If you set the "output_to_core" option to false before parsing (the default), then we call "output_path()" and create a new MIME::Body::File on that filename.

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.

Temporary File Creation

tmp_dir DIRECTORY

Instance method. Causes any temporary files created by this parser to be created in the given DIRECTORY.

If called without arguments, returns current value.

The default value is undef, which will cause new_tmpfile() to use the system default temporary directory.

new_tmpfile

Instance method. Return an IO handle to be used to hold temporary data during a parse.

The default uses MIME::Tools::tmpopen() to create a new temporary file, unless tmp_to_core() dictates otherwise, but you can override this. You shouldn't need to.

The location for temporary files can be changed on a per-parser basis with tmp_dir().

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.

Parse results and error recovery

last_error

Instance method. Return the error (if any) that we ignored in the last parse.

last_head

Instance method. Return the top-level MIME header of the last stream we attempted to parse. This is useful for replying to people who sent us bad MIME messages.

    ### Parse an input stream:
    eval { $entity = $parser->parse(\*STDIN) };
    if (!$entity) {    ### parse failed!
        my $decapitated = $parser->last_head;
        ...
    }
    

results

Instance method. Return an object containing lots of info from the last entity parsed. This will be an instance of class MIME::Parser::Results.

Maximizing speed

    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_to_core()              0   (will be MUCH faster)

Native I/O is much faster than object-oriented I/O. It's much faster to use <$foo> than $foo->getline. For backwards compatibility, 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 |");

Minimizing memory

    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_to_core is 1)
    tmp_to_core()              0   (will use MUCH less memory)

Maximizing tolerance of bad MIME

    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_to_core()              *** (doesn't matter)

Avoiding disk-based temporary files

    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_to_core()              1

You can veto tmpfiles entirely. 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.