NAME

MIME::Parser::AbstractFiler - manage file-output of the parser

SYNOPSIS

Before reading further, you should see MIME::Parser to make sure that you understand where this module fits into the grand scheme of things. Go on, do it now. I'll wait.

Ready? Ok... now read "DESCRIPTION" below, and everything else should make sense.

DESCRIPTION

How this class is used when parsing

When a MIME::Parser decides that it wants to output a file to disk, it uses its "Filer" object -- an instance of a MIME::Parser::AbstractFiler subclass -- to determine where to put the file.

Every parser has a single Filer object, which it uses for all parsing. You can get the Filer for a given $parser like this:

    $filer = $parser->filer;

At the beginning of each parse(), the filer's internal state is reset by the parser:

    $parser->filer->init_parse;

The parser can then get a path for each entity in the message by handing that entity's header (a MIME::Head) to the filer and having it do the work, like this:

    $new_file = $parser->filer->output_path($head);

Since it's nice to be able to clean up after a parse (especially a failed parse), the parser tells the filer when it has actually used a path:

    $parser->filer->purgeable($new_file);

Then, if you want to clean up the files which were created for a particular parse (and also any directories that the Filer created), you would do this:

    $parser->filer->purge;

Writing your own subclasses

The main concrete subclass of this class is MIME::Parser::Filer, which provides a lot of practical logic. You should subclass that class; see there for details.

In general, though, the only method you have to override is output_path():

    $filer->output_path($head);

This method is invoked by MIME::Parser when it wants to put a decoded message body in an output file. The method should return a path to the file to create. Failure is indicated by throwing an exception.

The path returned by output_path() should be "ready for open()": any necessary parent directories need to exist at that point. These directories can be created by the Filer, if course, and they should be marked as purgeable() if a purge should delete them.

PUBLIC INTERFACE

new INITARGS...

Class method, constructor. Create a new outputter for the given parser. Any subsequent arguments are given to init(), which subclasses should override for their own use (the default init does nothing).

logger

Instance method. Set/get a MIME::Tools::Logger object to tally any interesting messages.

init_parse

Instance method. Prepare to start parsing a new message. Subclasses should always be sure to invoke the inherited method.

output_path HEAD

Instance method, abstract. Given a MIME::Head for a file to be extracted, come up with a good output pathname for the extracted file. This is the only method you need to subclass.

purge

Instance method, final. Purge all files/directories created by the last parse. This method simply goes through the purgeable list in reverse order (see "purgeable") and removes all existing files/directories in it. You should not need to override this method.

purgeable [PATH]

Instance method, final. Add PATH to the list of "purgeable" files/directories (those which will be removed if you do a purge()). You should not need to override this method.

If PATH is not given, the "purgeable" list is returned. This may be used for more-sophisticated purging.

As a special case, invoking this method with a PATH that is an arrayref will replace the purgeable list with a copy of the array's contents, so [] may be used to clear the list.

Note that the "purgeable" list is cleared when a parser begins a new parse; therefore, if you want to use purge() to do cleanup, you must do so before starting a new parse!

AUTHOR

Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

$Revision: 6.106 $

cpanm MIME::Head

perl -MCPAN -e shell
install MIME::Head