{
    "mode": "perldoc",
    "parameter": "MIME::Parser::Filer",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/MIME%3A%3AParser%3A%3AFiler/json",
    "generated": "2026-06-13T11:44:57Z",
    "synopsis": "Before reading further, you should see MIME::Parser to make sure that you understand where this\nmodule fits into the grand scheme of things. Go on, do it now. I'll wait.\nReady? Ok... now read \"DESCRIPTION\" below, and everything else should make sense.",
    "sections": {
        "NAME": {
            "content": "MIME::Parser::Filer - manage file-output of the parser\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "Before reading further, you should see MIME::Parser to make sure that you understand where this\nmodule fits into the grand scheme of things. Go on, do it now. I'll wait.\n\nReady? Ok... now read \"DESCRIPTION\" below, and everything else should make sense.\n",
            "subsections": [
                {
                    "name": "Public interface",
                    "content": "### Create a \"filer\" of the desired class:\nmy $filer = MIME::Parser::FileInto->new($dir);\nmy $filer = MIME::Parser::FileUnder->new($basedir);\n...\n\n### Want added security?  Don't let outsiders name your files:\n$filer->ignorefilename(1);\n\n### Prepare for the parsing of a new top-level message:\n$filer->initparse;\n\n### Return the path where this message's data should be placed:\n$path = $filer->outputpath($head);\n"
                },
                {
                    "name": "Semi-public interface",
                    "content": "These methods might be overridden or ignored in some subclasses, so they don't all make sense in\nall circumstances:\n\n### Tweak the mapping from content-type to extension:\n$emap = $filer->outputextensionmap;\n$emap->{\"text/html\"} = \".htm\";\n"
                }
            ]
        },
        "DESCRIPTION": {
            "content": "",
            "subsections": [
                {
                    "name": "How this class is used when parsing",
                    "content": "When a MIME::Parser decides that it wants to output a file to disk, it uses its \"Filer\" object\n-- an instance of a MIME::Parser::Filer subclass -- to determine where to put the file.\n\nEvery parser has a single Filer object, which it uses for all parsing. You can get the Filer for\na given $parser like this:\n\n$filer = $parser->filer;\n\nAt the beginning of each \"parse()\", the filer's internal state is reset by the parser:\n\n$parser->filer->initparse;\n\nThe parser can then get a path for each entity in the message by handing that entity's header (a\nMIME::Head) to the filer and having it do the work, like this:\n\n$newfile = $parser->filer->outputpath($head);\n\nSince it's nice to be able to clean up after a parse (especially a failed parse), the parser\ntells the filer when it has actually used a path:\n\n$parser->filer->purgeable($newfile);\n\nThen, if you want to clean up the files which were created for a particular parse (and also any\ndirectories that the Filer created), you would do this:\n\n$parser->filer->purge;\n"
                },
                {
                    "name": "Writing your own subclasses",
                    "content": "There are two standard \"Filer\" subclasses (see below): MIME::Parser::FileInto, which throws all\nfiles from all parses into the same directory, and MIME::Parser::FileUnder (preferred), which\ncreates a subdirectory for each message. Hopefully, these will be sufficient for most uses, but\njust in case...\n\nThe only method you have to override is outputpath():\n\n$filer->outputpath($head);\n\nThis method is invoked by MIME::Parser when it wants to put a decoded message body in an output\nfile. The method should return a path to the file to create. Failure is indicated by throwing an\nexception.\n\nThe path returned by \"outputpath()\" should be \"ready for open()\": any necessary parent\ndirectories need to exist at that point. These directories can be created by the Filer, if\ncourse, and they should be marked as purgeable() if a purge should delete them.\n\nActually, if your issue is more *where* the files go than what they're named, you can use the\ndefault outputpath() method and just override one of its components:\n\n$dir  = $filer->outputdir($head);\n$name = $filer->outputfilename($head);\n...\n"
                }
            ]
        },
        "PUBLIC INTERFACE": {
            "content": "MIME::Parser::Filer\nThis is the abstract superclass of all \"filer\" objects.\n\nnew INITARGS...\n*Class method, constructor.* Create a new outputter for the given parser. Any subsequent\narguments are given to init(), which subclasses should override for their own use (the\ndefault init does nothing).\n\nresults RESULTS\n*Instance method.* Link this filer to a MIME::Parser::Results object which will tally the\nmessages. Notice that we avoid linking it to the parser to avoid circular reference!\n\ninitparse\n*Instance method.* Prepare to start parsing a new message. Subclasses should always be sure\nto invoke the inherited method.\n\nevilfilename FILENAME\n*Instance method.* Is this an evil filename; i.e., one which should not be used in\ngenerating a disk file name? It is if any of these are true:\n\n* it is empty or entirely whitespace\n* it contains leading or trailing whitespace\n* it is a string of dots: \".\", \"..\", etc.\n* it contains characters not in the set: \"A\" - \"Z\", \"a\" - \"z\",\n\"0\" - \"9\", \"-\", \"\", \"+\", \"=\", \".\", \",\", \"@\", \"#\",\n\"$\", and \" \".\n* it is too long\n\nIf you just want to change this behavior, you should override this method in the subclass of\nMIME::Parser::Filer that you use.\n\nWarning: at the time this method is invoked, the FILENAME has already been unmime'd into the\nlocal character set. If you're using any character set other than ASCII, ISO-8859-*, or\nUTF-8, the interpretation of the \"path\" characters might be very different, and you will\nprobably need to override this method. See \"unmime\" in MIME::WordDecoder for more details.\n\nNote: subclasses of MIME::Parser::Filer which override outputpath() might not consult this\nmethod; note, however, that the built-in subclasses do consult it.\n\n*Thanks to Andrew Pimlott for finding a real dumb bug in the original version. Thanks to\nNickolay Saukh for noting that evil is in the eye of the beholder.*\n\nexorcisefilename FILENAME\n*Instance method.* If a given filename is evil (see \"evilfilename\") we try to rescue it by\nperforming some basic operations: shortening it, removing bad characters, etc., and checking\neach against evilfilename().\n\nReturns the exorcised filename (which is guaranteed to not be evil), or undef if it could\nnot be salvaged.\n\nWarning: at the time this method is invoked, the FILENAME has already been unmime'd into the\nlocal character set. If you're using anything character set other than ASCII, ISO-8859-*, or\nUTF-8, the interpretation of the \"path\" characters might be very very different, and you\nwill probably need to override this method. See \"unmime\" in MIME::WordDecoder for more\ndetails.\n\nfindunusedpath DIR, FILENAME\n*Instance method, subclasses only.* We have decided on an output directory and tentative\nfilename, but there is a chance that it might already exist. Keep adding a numeric suffix\n\"-1\", \"-2\", etc. to the filename until an unused path is found, and then return that path.\n\nThe suffix is actually added before the first \".\" in the filename is there is one; for\nexample:\n\npicture.gif       archive.tar.gz      readme\npicture-1.gif     archive-1.tar.gz    readme-1\npicture-2.gif     archive-2.tar.gz    readme-2\n...               ...                 ...\npicture-10.gif\n...\n\nThis can be a costly operation, and risky if you don't want files renamed, so it is in your\nbest interest to minimize situations where these kinds of collisions occur. Unfortunately,\nif a multipart message gives all of its parts the same recommended filename, and you are\nplacing them all in the same directory, this method might be unavoidable.\n\nignorefilename [YESNO]\n*Instance method.* Return true if we should always ignore recommended filenames in messages,\nchoosing instead to always generate our own filenames. With argument, sets this value.\n\nNote: subclasses of MIME::Parser::Filer which override outputpath() might not honor this\nsetting; note, however, that the built-in subclasses honor it.\n\noutputdir HEAD\n*Instance method.* Return the output directory for the given header. The default method\nreturns \".\".\n\noutputfilename HEAD\n*Instance method, subclasses only.* A given recommended filename was either not given, or it\nwas judged to be evil. Return a fake name, possibly using information in the message HEADer.\nNote that this is just the filename, not the full path.\n\nUsed by outputpath(). If you're using the default \"outputpath()\", you probably don't need\nto worry about avoiding collisions with existing files; we take care of that in\nfindunusedpath().\n\noutputprefix [PREFIX]\n*Instance method.* Get the short string that all filenames for extracted body-parts will\nbegin with (assuming that there is no better \"recommended filename\"). The default is \"msg\".\n\nIf PREFIX *is not* given, the current output prefix is returned. If PREFIX *is* given, the\noutput prefix is set to the new value, and the previous value is returned.\n\nUsed by outputfilename().\n\nNote: subclasses of MIME::Parser::Filer which override outputpath() or outputfilename()\nmight not honor this setting; note, however, that the built-in subclasses honor it.\n\noutputtypeext\n*Instance method.* Return a reference to the hash used by the default outputfilename() for\nmapping from content-types to extensions when there is no default extension to use.\n\n$emap = $filer->outputtypemap;\n$emap->{'text/plain'} = '.txt';\n$emap->{'text/html'}  = '.html';\n$emap->{'text/*'}     = '.txt';\n$emap->{'*/*'}        = '.dat';\n\nNote: subclasses of MIME::Parser::Filer which override outputpath() or outputfilename()\nmight not consult this hash; note, however, that the built-in subclasses consult it.\n\noutputpath HEAD\n*Instance method, subclasses only.* Given a MIME head for a file to be extracted, come up\nwith a good output pathname for the extracted file. This is the only method you need to\nworry about if you are building a custom filer.\n\nThe default implementation does a lot of work; subclass implementers *really* should try to\njust override its components instead of the whole thing. It works basically as follows:\n\n$directory = $self->outputdir($head);\n\n$filename = $head->recommendedfilename();\nif (!$filename or\n$self->ignorefilename() or\n$self->evilfilename($filename)) {\n$filename = $self->outputfilename($head);\n}\n\nreturn $self->findunusedpath($directory, $filename);\n\nNote: There are many, many, many ways you might want to control the naming of files, based\non your application. If you don't like the behavior of this function, you can easily define\nyour own subclass of MIME::Parser::Filer and override it there.\n\nNote: Nickolay Saukh pointed out that, given the subjective nature of what is \"evil\", this\nfunction really shouldn't *warn* about an evil filename, but maybe just issue a *debug*\nmessage. I considered that, but then I thought: if debugging were off, people wouldn't know\nwhy (or even if) a given filename had been ignored. In mail robots that depend on\nexternally-provided filenames, this could cause hard-to-diagnose problems. So, the message\nis still a warning.\n\n*Thanks to Laurent Amon for pointing out problems with the original implementation, and for\nmaking some good suggestions. Thanks also to Achim Bohnet for pointing out that there should\nbe a hookless, OO way of overriding the output path.*\n\npurge\n*Instance method, final.* Purge all files/directories created by the last parse. This method\nsimply goes through the purgeable list in reverse order (see \"purgeable\") and removes all\nexisting files/directories in it. You should not need to override this method.\n\npurgeable [FILE]\n*Instance method, final.* Add FILE to the list of \"purgeable\" files/directories (those which\nwill be removed if you do a \"purge()\"). You should not need to override this method.\n\nIf FILE is not given, the \"purgeable\" list is returned. This may be used for\nmore-sophisticated purging.\n\nAs a special case, invoking this method with a FILE that is an arrayref will replace the\npurgeable list with a copy of the array's contents, so [] may be used to clear the list.\n\nNote that the \"purgeable\" list is cleared when a parser begins a new parse; therefore, if\nyou want to use purge() to do cleanup, you *must* do so *before* starting a new parse!\n\nMIME::Parser::FileInto\nThis concrete subclass of MIME::Parser::Filer supports filing into a given directory.\n\ninit DIRECTORY\n*Instance method, initiallizer.* Set the directory where all files will go.\n\nMIME::Parser::FileUnder\nThis concrete subclass of MIME::Parser::Filer supports filing under a given directory, using one\nsubdirectory per message, but with all message parts in the same directory.\n\ninit BASEDIR, OPTSHASH...\n*Instance method, initiallizer.* Set the base directory which will contain the message\ndirectories. If used, then each parse of begins by creating a new subdirectory of BASEDIR\nwhere the actual parts of the message are placed. OPTSHASH can contain the following:\n\nDirName\nExplicitly set the name of the subdirectory which is created. The default is to use the\ntime, process id, and a sequence number, but you might want a predictable directory.\n\nPurge\nAutomatically purge the contents of the directory (including all subdirectories) before\neach parse. This is really only needed if using an explicit DirName, and is provided as\na convenience only. Currently we use the 1-arg form of File::Path::rmtree; you should\nfamiliarize yourself with the caveats therein.\n\nThe outputdir() will return the path to this message-specific directory until the next\nparse is begun, so you can do this:\n\nuse File::Path;\n\n$parser->outputunder(\"/tmp\");\n$ent = eval { $parser->parseopen($msg); };   ### parse\nif (!$ent) {         ### parse failed\nrmtree($parser->outputdir);\ndie \"parse failed: $@\";\n}\nelse {               ### parse succeeded\n...do stuff...\n}\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "MIME::Tools, MIME::Parser\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).\n\nAll rights reserved. This program is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.\n",
            "subsections": []
        }
    },
    "summary": "MIME::Parser::Filer - manage file-output of the parser",
    "flags": [],
    "examples": [],
    "see_also": []
}