GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


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'}  = '.php';
               $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...
               }

SEE ALSO

       MIME::Tools, MIME::Parser

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.



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.087 seconds. Last modified: November 04 2018 12:49:43.