Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MIME::Parser::Filer(3)User Contributed Perl DocumentatioMIME::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 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...
	       }

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.

perl v5.32.1			  2013-08-13		MIME::Parser::Filer(3)

NAME | SYNOPSIS | DESCRIPTION | PUBLIC INTERFACE | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MIME::Parser::Filer&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help