.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MIME::Parser::Filer 3"
.TH MIME::Parser::Filer 3 "2013-08-13" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MIME::Parser::Filer \- manage file\-output of the parser
.SH "SYNOPSIS"
.IX Header "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.
.PP
Ready?  Ok... now read \*(L"\s-1DESCRIPTION\*(R"\s0 below, and everything else
should make sense.
.SS "Public interface"
.IX Subsection "Public interface"
.Vb 4
\&    ### 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\*(Aqt 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\*(Aqs data should be placed:
\&    $path = $filer\->output_path($head);
.Ve
.SS "Semi-public interface"
.IX Subsection "Semi-public interface"
These methods might be overridden or ignored in some subclasses,
so they don't all make sense in all circumstances:
.PP
.Vb 3
\&    ### Tweak the mapping from content\-type to extension:
\&    $emap = $filer\->output_extension_map;
\&    $emap\->{"text/html"} = ".htm";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "How this class is used when parsing"
.IX Subsection "How this class is used when parsing"
When a MIME::Parser decides that it wants to output a file to disk,
it uses its \*(L"Filer\*(R" object \*(-- an instance of a MIME::Parser::Filer
subclass \*(-- to determine where to put the file.
.PP
Every parser has a single Filer object, which it uses for all
parsing.  You can get the Filer for a given \f(CW$parser\fR like this:
.PP
.Vb 1
\&    $filer = $parser\->filer;
.Ve
.PP
At the beginning of each \f(CW\*(C`parse()\*(C'\fR, the filer's internal state
is reset by the parser:
.PP
.Vb 1
\&    $parser\->filer\->init_parse;
.Ve
.PP
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:
.PP
.Vb 1
\&    $new_file = $parser\->filer\->output_path($head);
.Ve
.PP
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:
.PP
.Vb 1
\&    $parser\->filer\->purgeable($new_file);
.Ve
.PP
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:
.PP
.Vb 1
\&    $parser\->filer\->purge;
.Ve
.SS "Writing your own subclasses"
.IX Subsection "Writing your own subclasses"
There are two standard \*(L"Filer\*(R" subclasses (see below):
\&\fBMIME::Parser::FileInto\fR, which throws all files from all parses
into the same directory, and \fBMIME::Parser::FileUnder\fR (preferred), which
creates a subdirectory for each message.  Hopefully, these will be
sufficient for most uses, but just in case...
.PP
The only method you have to override is \fBoutput_path()\fR:
.PP
.Vb 1
\&    $filer\->output_path($head);
.Ve
.PP
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.
.PP
The path returned by \f(CW\*(C`output_path()\*(C'\fR should be \*(L"ready for \fBopen()\fR\*(R":
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 \fB\fBpurgeable()\fB\fR if a purge should delete them.
.PP
Actually, if your issue is more \fIwhere\fR the files go than
what they're named, you can use the default \fBoutput_path()\fR
method and just override one of its components:
.PP
.Vb 3
\&    $dir  = $filer\->output_dir($head);
\&    $name = $filer\->output_filename($head);
\&    ...
.Ve
.SH "PUBLIC INTERFACE"
.IX Header "PUBLIC INTERFACE"
.SS "MIME::Parser::Filer"
.IX Subsection "MIME::Parser::Filer"
This is the abstract superclass of all \*(L"filer\*(R" objects.
.IP "new \s-1INITARGS...\s0" 4
.IX Item "new INITARGS..."
\&\fIClass method, constructor.\fR
Create a new outputter for the given parser.
Any subsequent arguments are given to \fBinit()\fR, which subclasses should
override for their own use (the default init does nothing).
.IP "results \s-1RESULTS\s0" 4
.IX Item "results RESULTS"
\&\fIInstance method.\fR
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!
.IP "init_parse" 4
.IX Item "init_parse"
\&\fIInstance method.\fR
Prepare to start parsing a new message.
Subclasses should always be sure to invoke the inherited method.
.IP "evil_filename \s-1FILENAME\s0" 4
.IX Item "evil_filename FILENAME"
\&\fIInstance method.\fR
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:
.Sp
.Vb 7
\&    * 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
.Ve
.Sp
If you just want to change this behavior, you should override
this method in the subclass of MIME::Parser::Filer that you use.
.Sp
\&\fBWarning:\fR at the time this method is invoked, the \s-1FILENAME\s0 has
already been unmime'd into the local character set.
If you're using any character set other than \s-1ASCII,\s0 ISO\-8859\-*,
or \s-1UTF\-8,\s0 the interpretation of the \*(L"path\*(R" characters might be
very different, and you will probably need to override this method.
See \*(L"unmime\*(R" in MIME::WordDecoder for more details.
.Sp
\&\fBNote:\fR subclasses of MIME::Parser::Filer which override
\&\fBoutput_path()\fR might not consult this method; note, however, that
the built-in subclasses do consult it.
.Sp
\&\fIThanks 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.\fR
.IP "exorcise_filename \s-1FILENAME\s0" 4
.IX Item "exorcise_filename FILENAME"
\&\fIInstance method.\fR
If a given filename is evil (see \*(L"evil_filename\*(R") we try to
rescue it by performing some basic operations: shortening it,
removing bad characters, etc., and checking each against
\&\fBevil_filename()\fR.
.Sp
Returns the exorcised filename (which is guaranteed to not
be evil), or undef if it could not be salvaged.
.Sp
\&\fBWarning:\fR at the time this method is invoked, the \s-1FILENAME\s0 has
already been unmime'd into the local character set.
If you're using anything character set other than \s-1ASCII,\s0 ISO\-8859\-*,
or \s-1UTF\-8,\s0 the interpretation of the \*(L"path\*(R" characters might be very
very different, and you will probably need to override this method.
See \*(L"unmime\*(R" in MIME::WordDecoder for more details.
.IP "find_unused_path \s-1DIR, FILENAME\s0" 4
.IX Item "find_unused_path DIR, FILENAME"
\&\fIInstance method, subclasses only.\fR
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 \*(L"\-1\*(R", \*(L"\-2\*(R", etc. to the filename
until an unused path is found, and then return that path.
.Sp
The suffix is actually added before the first \*(L".\*(R" in the filename
is there is one; for example:
.Sp
.Vb 6
\&    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
\&    ...
.Ve
.Sp
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.
.IP "ignore_filename [\s-1YESNO\s0]" 4
.IX Item "ignore_filename [YESNO]"
\&\fIInstance method.\fR
Return true if we should always ignore recommended filenames in
messages, choosing instead to always generate our own filenames.
With argument, sets this value.
.Sp
\&\fBNote:\fR subclasses of MIME::Parser::Filer which override
\&\fBoutput_path()\fR might not honor this setting; note, however, that
the built-in subclasses honor it.
.IP "output_dir \s-1HEAD\s0" 4
.IX Item "output_dir HEAD"
\&\fIInstance method.\fR
Return the output directory for the given header.
The default method returns \*(L".\*(R".
.IP "output_filename \s-1HEAD\s0" 4
.IX Item "output_filename HEAD"
\&\fIInstance method, subclasses only.\fR
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.
.Sp
Used by \fBoutput_path()\fR.
If you're using the default \f(CW\*(C`output_path()\*(C'\fR, you probably don't
need to worry about avoiding collisions with existing files;
we take care of that in \fBfind_unused_path()\fR.
.IP "output_prefix [\s-1PREFIX\s0]" 4
.IX Item "output_prefix [PREFIX]"
\&\fIInstance method.\fR
Get the short string that all filenames for extracted body-parts
will begin with (assuming that there is no better \*(L"recommended filename\*(R").
The default is \fI\*(L"msg\*(R"\fR.
.Sp
If \s-1PREFIX\s0 \fIis not\fR given, the current output prefix is returned.
If \s-1PREFIX\s0 \fIis\fR given, the output prefix is set to the new value,
and the previous value is returned.
.Sp
Used by \fBoutput_filename()\fR.
.Sp
\&\fBNote:\fR subclasses of MIME::Parser::Filer which override
\&\fBoutput_path()\fR or \fBoutput_filename()\fR might not honor this setting;
note, however, that the built-in subclasses honor it.
.IP "output_type_ext" 4
.IX Item "output_type_ext"
\&\fIInstance method.\fR
Return a reference to the hash used by the default
\&\fBoutput_filename()\fR for mapping from content-types
to extensions when there is no default extension to use.
.Sp
.Vb 5
\&    $emap = $filer\->output_typemap;
\&    $emap\->{\*(Aqtext/plain\*(Aq} = \*(Aq.txt\*(Aq;
\&    $emap\->{\*(Aqtext/html\*(Aq}  = \*(Aq.html\*(Aq;
\&    $emap\->{\*(Aqtext/*\*(Aq}     = \*(Aq.txt\*(Aq;
\&    $emap\->{\*(Aq*/*\*(Aq}        = \*(Aq.dat\*(Aq;
.Ve
.Sp
\&\fBNote:\fR subclasses of MIME::Parser::Filer which override
\&\fBoutput_path()\fR or \fBoutput_filename()\fR might not consult this hash;
note, however, that the built-in subclasses consult it.
.IP "output_path \s-1HEAD\s0" 4
.IX Item "output_path HEAD"
\&\fIInstance method, subclasses only.\fR
Given a \s-1MIME\s0 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.
.Sp
The default implementation does a lot of work; subclass
implementers \fIreally\fR should try to just override its components
instead of the whole thing.  It works basically as follows:
.Sp
.Vb 1
\&    $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);
.Ve
.Sp
\&\fBNote:\fR 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.
.Sp
\&\fBNote:\fR Nickolay Saukh pointed out that, given the subjective nature of
what is \*(L"evil\*(R", this function really shouldn't \fIwarn\fR about an evil
filename, but maybe just issue a \fIdebug\fR 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.
.Sp
\&\fIThanks 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, \s-1OO\s0 way of
overriding the output path.\fR
.IP "purge" 4
.IX Item "purge"
\&\fIInstance method, final.\fR
Purge all files/directories created by the last parse.
This method simply goes through the purgeable list in reverse order
(see \*(L"purgeable\*(R") and removes all existing files/directories in it.
You should not need to override this method.
.IP "purgeable [\s-1FILE\s0]" 4
.IX Item "purgeable [FILE]"
\&\fIInstance method, final.\fR
Add \s-1FILE\s0 to the list of \*(L"purgeable\*(R" files/directories (those which
will be removed if you do a \f(CW\*(C`purge()\*(C'\fR).
You should not need to override this method.
.Sp
If \s-1FILE\s0 is not given, the \*(L"purgeable\*(R" list is returned.
This may be used for more-sophisticated purging.
.Sp
As a special case, invoking this method with a \s-1FILE\s0 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.
.Sp
Note that the \*(L"purgeable\*(R" list is cleared when a parser begins a
new parse; therefore, if you want to use \fBpurge()\fR to do cleanup,
you \fImust\fR do so \fIbefore\fR starting a new parse!
.SS "MIME::Parser::FileInto"
.IX Subsection "MIME::Parser::FileInto"
This concrete subclass of MIME::Parser::Filer supports filing
into a given directory.
.IP "init \s-1DIRECTORY\s0" 4
.IX Item "init DIRECTORY"
\&\fIInstance method, initiallizer.\fR
Set the directory where all files will go.
.SS "MIME::Parser::FileUnder"
.IX Subsection "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.
.IP "init \s-1BASEDIR, OPTSHASH...\s0" 4
.IX Item "init BASEDIR, OPTSHASH..."
\&\fIInstance method, initiallizer.\fR
Set the base directory which will contain the message directories.
If used, then each parse of begins by creating a new subdirectory
of \s-1BASEDIR\s0 where the actual parts of the message are placed.
\&\s-1OPTSHASH\s0 can contain the following:
.RS 4
.IP "DirName" 4
.IX Item "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.
.IP "Purge" 4
.IX Item "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.
.RE
.RS 4
.Sp
The \fBoutput_dir()\fR will return the path to this message-specific directory
until the next parse is begun, so you can do this:
.Sp
.Vb 1
\&    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...
\&    }
.Ve
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
MIME::Tools, MIME::Parser
.SH "AUTHOR"
.IX Header "AUTHOR"
Eryq (\fIeryq@zeegee.com\fR), ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
.PP
All rights reserved.  This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.