MIME::Parser::Filer - manage file-output of the parser
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...
### 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);
These methods might be overriden 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";
$parser->filer($filer);
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. There are two
standard "Filer" subclasses (see below). To implement your own custom
behavior, however, you may want to author your own Filer subclass.
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.
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);
...
This is the abstract superclass of all "filer" objects.
If you just want to change this behavior, you should override this method in the subclass of MIME::Parser::Filer that you use.
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.
Note: This method used to be a lot stricter, but it unnecessailry inconvenienced users on non-ASCII systems.
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.
Note: subclasses of MIME::Parser::Filer which override output_path() might not honor this setting; note, however, that the built-in subclasses honor it.
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().
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.
$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.
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.
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.
This concrete subclass of MIME::Parser::Filer supports filing into a given directory.
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.
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...
}
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.403 $