mime::parser::filer(3)

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 overriden or ignored in some sub
classes, so they don't all make sense in all circum
stances:
    ### 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 mes sage 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::FileUn der (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 ppuurrggeeaabbllee(()) 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 mes
sages. Notice that we avoid linking it to the parser
to avoid circular reference!
init_parse: Instance method. Prepare to start parsing a new mes sage. 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
* it is a string of dots: ".", "..", etc.
* it contains a known "path" character: '/' '� ':'

'[' ']'
* 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 FILE NAME has already been unmime'd into the local charac
ter 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_file_ name().; 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 FILE NAME has already been unmime'd into the local charac
ter 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, how ever, 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 file names for extracted body-parts will begin with (assum
ing 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 sub
classes honor it.
output_type_ext: Instance method. Return a reference to the hash used by the default output_filename() for mapping from con tent-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; sub
class 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, $file; name);
Note: There are many, many, many ways you might want
to control the naming of files, based on your applica
tion. If you don't like the behavior of this func
tion, you can easily define your own subclass of
MIME::Parser::Filer and override it there.
Note: Nickolay Saukh pointed out that, given the sub
jective 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 over_ riding 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/directo
ries 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 subdirec
tory 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, pro
cess 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 your
self with the caveats therein.; The output_dir() will return the path to this messagespecific 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).

VERSION

$Revision: 5.406 $

docs.sk

comprehensive documentation repository