Ubuntu Manpage: MIME::Parser::Filer - manage file-output of the parser

Provided by: libmime-tools-perl_5.510-1_all

NAME

       MIME::Parser::Filer - 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.

   Public interface
           ### Create a "filer" of the desired class:
           my $filer = MIME::Parser::FileInto->new($dir);
           my $filer = MIME::Parser::FileUnder->new($basedir);
           ...

           ### Want added security?  Don't let outsiders name your files:
           $filer->ignore_filename(1);

           ### Prepare for the parsing of a new top-level message:
           $filer->init_parse;

           ### Return the path where this message's data should be placed:
           $path = $filer->output_path($head);

   Semi-public interface
       These methods might be overridden or ignored in some subclasses, so they don't all make
       sense in all circumstances:

           ### Tweak the mapping from content-type to extension:
           $emap = $filer->output_extension_map;
           $emap->{"text/html"} = ".htm";

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::Filer 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
       There are two standard "Filer" subclasses (see below): MIME::Parser::FileInto, which
       throws all files from all parses into the same directory, and MIME::Parser::FileUnder
       (preferred), which creates a subdirectory for each message.  Hopefully, these will be
       sufficient for most uses, but just in case...

       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.

       Actually, if your issue is more where the files go than what they're named, you can use
       the default output_path() method and just override one of its components:

           $dir  = $filer->output_dir($head);
           $name = $filer->output_filename($head);
           ...

PUBLIC INTERFACE

MIME::Parser::Filer
This is the abstract superclass of all "filer" objects.

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

results RESULTS
Instance method. Link this filer to a MIME::Parser::Results object which will tally
the messages. Notice that we avoid linking it to the parser to avoid circular
reference!

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

evil_filename FILENAME
Instance method. Is this an evil filename; i.e., one which should not be used in
generating a disk file name? It is if any of these are true:

* it is empty or entirely whitespace
* it contains leading or trailing whitespace
* it is a string of dots: ".", "..", etc.
* it contains characters not in the set: "A" - "Z", "a" - "z",
"0" - "9", "-", "_", "+", "=", ".", ",", "@", "#",
"$", and " ".
* it is too long

If you just want to change this behavior, you should override this method in the
subclass of MIME::Parser::Filer that you use.

Warning: at the time this method is invoked, the FILENAME has already been unmime'd
into the local character set. If you're using any character set other than ASCII,
ISO-8859-*, or UTF-8, the interpretation of the "path" characters might be very
different, and you will probably need to override this method. See "unmime" in
MIME::WordDecoder for more details.

Note: subclasses of MIME::Parser::Filer which override output_path() might not consult
this method; note, however, that the built-in subclasses do consult it.

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.

exorcise_filename FILENAME
Instance method. If a given filename is evil (see "evil_filename") we try to rescue
it by performing some basic operations: shortening it, removing bad characters, etc.,
and checking each against evil_filename().

Returns the exorcised filename (which is guaranteed to not be evil), or undef if it
could not be salvaged.

Warning: at the time this method is invoked, the FILENAME has already been unmime'd
into the local character set. If you're using anything character set other than
ASCII, ISO-8859-*, or UTF-8, the interpretation of the "path" characters might be very
very different, and you will probably need to override this method. See "unmime" in
MIME::WordDecoder for more details.

find_unused_path DIR, FILENAME
Instance method, subclasses only. We have decided on an output directory and
tentative filename, but there is a chance that it might already exist. Keep adding a
numeric suffix "-1", "-2", etc. to the filename until an unused path is found, and
then return that path.

The suffix is actually added before the first "." in the filename is there is one; for
example:

picture.gif archive.tar.gz readme
picture-1.gif archive-1.tar.gz readme-1
picture-2.gif archive-2.tar.gz readme-2
... ... ...
picture-10.gif
...

This can be a costly operation, and risky if you don't want files renamed, so it is in
your best interest to minimize situations where these kinds of collisions occur.
Unfortunately, if a multipart message gives all of its parts the same recommended
filename, and you are placing them all in the same directory, this method might be
unavoidable.

ignore_filename [YESNO]
Instance method. Return true if we should always ignore recommended filenames in
messages, choosing instead to always generate our own filenames. With argument, sets
this value.

Note: subclasses of MIME::Parser::Filer which override output_path() might not honor
this setting; note, however, that the built-in subclasses honor it.

output_dir HEAD
Instance method. Return the output directory for the given header. The default
method returns ".".

output_filename HEAD
Instance method, subclasses only. A given recommended filename was either not given,
or it was judged to be evil. Return a fake name, possibly using information in the
message HEADer. Note that this is just the filename, not the full path.

Used by output_path(). If you're using the default "output_path()", you probably
don't need to worry about avoiding collisions with existing files; we take care of
that in find_unused_path().

output_prefix [PREFIX]
Instance method. Get the short string that all filenames for extracted body-parts
will begin with (assuming that there is no better "recommended filename"). The
default is "msg".

If PREFIX is not given, the current output prefix is returned. If PREFIX is given,
the output prefix is set to the new value, and the previous value is returned.

Used by output_filename().

Note: subclasses of MIME::Parser::Filer which override output_path() or
output_filename() might not honor this setting; note, however, that the built-in
subclasses honor it.

output_type_ext
Instance method. Return a reference to the hash used by the default output_filename()
for mapping from content-types to extensions when there is no default extension to
use.

$emap = $filer->output_typemap;
$emap->{'text/plain'} = '.txt';
$emap->{'text/html'} = '.html';
$emap->{'text/*'} = '.txt';
$emap->{'*/*'} = '.dat';

Note: subclasses of MIME::Parser::Filer which override output_path() or
output_filename() might not consult this hash; note, however, that the built-in
subclasses consult it.

output_path HEAD
Instance method, subclasses only. 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 worry about if you are building a custom filer.

The default implementation does a lot of work; subclass implementers really should try
to just override its components instead of the whole thing. It works basically as
follows:

$directory = $self->output_dir($head);

$filename = $head->recommended_filename();
if (!$filename or
$self->ignore_filename() or
$self->evil_filename($filename)) {
$filename = $self->output_filename($head);
}

return $self->find_unused_path($directory, $filename);

Note: There are many, many, many ways you might want to control the naming of files,
based on your application. If you don't like the behavior of this function, you can
easily define your own subclass of MIME::Parser::Filer and override it there.

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.

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.

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 [FILE]
Instance method, final. Add FILE 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 FILE 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 FILE 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!

MIME::Parser::FileInto
This concrete subclass of MIME::Parser::Filer supports filing into a given directory.

init DIRECTORY
Instance method, initiallizer. Set the directory where all files will go.

MIME::Parser::FileUnder
This concrete subclass of MIME::Parser::Filer supports filing under a given directory,
using one subdirectory per message, but with all message parts in the same directory.

init BASEDIR, OPTSHASH...
Instance method, initiallizer. Set the base directory which will contain the message
directories. If used, then each parse of begins by creating a new subdirectory of
BASEDIR where the actual parts of the message are placed. OPTSHASH can contain the
following:

DirName
Explicitly set the name of the subdirectory which is created. The default is to
use the time, process id, and a sequence number, but you might want a predictable
directory.

Purge
Automatically purge the contents of the directory (including all subdirectories)
before each parse. This is really only needed if using an explicit DirName, and
is provided as a convenience only. Currently we use the 1-arg form of
File::Path::rmtree; you should familiarize yourself with the caveats therein.

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

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.

NAME

SYNOPSIS

DESCRIPTION

PUBLIC INTERFACE

SEE ALSO

AUTHOR