1MIME::Parser::Filer(3)User Contributed Perl DocumentationMIME::Parser::Filer(3)
2
3
4

NAME

6       MIME::Parser::Filer - manage file-output of the parser
7

SYNOPSIS

9       Before reading further, you should see MIME::Parser to make sure that
10       you understand where this module fits into the grand scheme of things.
11       Go on, do it now.  I'll wait.
12
13       Ready?  Ok... now read "DESCRIPTION" below, and everything else should
14       make sense.
15
16   Public interface
17           ### Create a "filer" of the desired class:
18           my $filer = MIME::Parser::FileInto->new($dir);
19           my $filer = MIME::Parser::FileUnder->new($basedir);
20           ...
21
22           ### Want added security?  Don't let outsiders name your files:
23           $filer->ignore_filename(1);
24
25           ### Prepare for the parsing of a new top-level message:
26           $filer->init_parse;
27
28           ### Return the path where this message's data should be placed:
29           $path = $filer->output_path($head);
30
31   Semi-public interface
32       These methods might be overridden or ignored in some subclasses, so
33       they don't all make sense in all circumstances:
34
35           ### Tweak the mapping from content-type to extension:
36           $emap = $filer->output_extension_map;
37           $emap->{"text/html"} = ".htm";
38

DESCRIPTION

40   How this class is used when parsing
41       When a MIME::Parser decides that it wants to output a file to disk, it
42       uses its "Filer" object -- an instance of a MIME::Parser::Filer
43       subclass -- to determine where to put the file.
44
45       Every parser has a single Filer object, which it uses for all parsing.
46       You can get the Filer for a given $parser like this:
47
48           $filer = $parser->filer;
49
50       At the beginning of each "parse()", the filer's internal state is reset
51       by the parser:
52
53           $parser->filer->init_parse;
54
55       The parser can then get a path for each entity in the message by
56       handing that entity's header (a MIME::Head) to the filer and having it
57       do the work, like this:
58
59           $new_file = $parser->filer->output_path($head);
60
61       Since it's nice to be able to clean up after a parse (especially a
62       failed parse), the parser tells the filer when it has actually used a
63       path:
64
65           $parser->filer->purgeable($new_file);
66
67       Then, if you want to clean up the files which were created for a
68       particular parse (and also any directories that the Filer created), you
69       would do this:
70
71           $parser->filer->purge;
72
73   Writing your own subclasses
74       There are two standard "Filer" subclasses (see below):
75       MIME::Parser::FileInto, which throws all files from all parses into the
76       same directory, and MIME::Parser::FileUnder (preferred), which creates
77       a subdirectory for each message.  Hopefully, these will be sufficient
78       for most uses, but just in case...
79
80       The only method you have to override is output_path():
81
82           $filer->output_path($head);
83
84       This method is invoked by MIME::Parser when it wants to put a decoded
85       message body in an output file.  The method should return a path to the
86       file to create.  Failure is indicated by throwing an exception.
87
88       The path returned by "output_path()" should be "ready for open()": any
89       necessary parent directories need to exist at that point.  These
90       directories can be created by the Filer, if course, and they should be
91       marked as purgeable() if a purge should delete them.
92
93       Actually, if your issue is more where the files go than what they're
94       named, you can use the default output_path() method and just override
95       one of its components:
96
97           $dir  = $filer->output_dir($head);
98           $name = $filer->output_filename($head);
99           ...
100

PUBLIC INTERFACE

102   MIME::Parser::Filer
103       This is the abstract superclass of all "filer" objects.
104
105       new INITARGS...
106           Class method, constructor.  Create a new outputter for the given
107           parser.  Any subsequent arguments are given to init(), which
108           subclasses should override for their own use (the default init does
109           nothing).
110
111       results RESULTS
112           Instance method.  Link this filer to a MIME::Parser::Results object
113           which will tally the messages.  Notice that we avoid linking it to
114           the parser to avoid circular reference!
115
116       init_parse
117           Instance method.  Prepare to start parsing a new message.
118           Subclasses should always be sure to invoke the inherited method.
119
120       evil_filename FILENAME
121           Instance method.  Is this an evil filename; i.e., one which should
122           not be used in generating a disk file name?  It is if any of these
123           are true:
124
125               * it is empty or entirely whitespace
126               * it contains leading or trailing whitespace
127               * it is a string of dots: ".", "..", etc.
128               * it contains characters not in the set: "A" - "Z", "a" - "z",
129                 "0" - "9", "-", "_", "+", "=", ".", ",", "@", "#",
130                 "$", and " ".
131               * it is too long
132
133           If you just want to change this behavior, you should override this
134           method in the subclass of MIME::Parser::Filer that you use.
135
136           Warning: at the time this method is invoked, the FILENAME has
137           already been unmime'd into the local character set.  If you're
138           using any character set other than ASCII, ISO-8859-*, or UTF-8, the
139           interpretation of the "path" characters might be very different,
140           and you will probably need to override this method.  See "unmime"
141           in MIME::WordDecoder for more details.
142
143           Note: subclasses of MIME::Parser::Filer which override
144           output_path() might not consult this method; note, however, that
145           the built-in subclasses do consult it.
146
147           Thanks to Andrew Pimlott for finding a real dumb bug in the
148           original version.  Thanks to Nickolay Saukh for noting that evil is
149           in the eye of the beholder.
150
151       exorcise_filename FILENAME
152           Instance method.  If a given filename is evil (see "evil_filename")
153           we try to rescue it by performing some basic operations: shortening
154           it, removing bad characters, etc., and checking each against
155           evil_filename().
156
157           Returns the exorcised filename (which is guaranteed to not be
158           evil), or undef if it could not be salvaged.
159
160           Warning: at the time this method is invoked, the FILENAME has
161           already been unmime'd into the local character set.  If you're
162           using anything character set other than ASCII, ISO-8859-*, or
163           UTF-8, the interpretation of the "path" characters might be very
164           very different, and you will probably need to override this method.
165           See "unmime" in MIME::WordDecoder for more details.
166
167       find_unused_path DIR, FILENAME
168           Instance method, subclasses only.  We have decided on an output
169           directory and tentative filename, but there is a chance that it
170           might already exist.  Keep adding a numeric suffix "-1", "-2", etc.
171           to the filename until an unused path is found, and then return that
172           path.
173
174           The suffix is actually added before the first "." in the filename
175           is there is one; for example:
176
177               picture.gif       archive.tar.gz      readme
178               picture-1.gif     archive-1.tar.gz    readme-1
179               picture-2.gif     archive-2.tar.gz    readme-2
180               ...               ...                 ...
181               picture-10.gif
182               ...
183
184           This can be a costly operation, and risky if you don't want files
185           renamed, so it is in your best interest to minimize situations
186           where these kinds of collisions occur.  Unfortunately, if a
187           multipart message gives all of its parts the same recommended
188           filename, and you are placing them all in the same directory, this
189           method might be unavoidable.
190
191       ignore_filename [YESNO]
192           Instance method.  Return true if we should always ignore
193           recommended filenames in messages, choosing instead to always
194           generate our own filenames.  With argument, sets this value.
195
196           Note: subclasses of MIME::Parser::Filer which override
197           output_path() might not honor this setting; note, however, that the
198           built-in subclasses honor it.
199
200       output_dir HEAD
201           Instance method.  Return the output directory for the given header.
202           The default method returns ".".
203
204       output_filename HEAD
205           Instance method, subclasses only.  A given recommended filename was
206           either not given, or it was judged to be evil.  Return a fake name,
207           possibly using information in the message HEADer.  Note that this
208           is just the filename, not the full path.
209
210           Used by output_path().  If you're using the default
211           "output_path()", you probably don't need to worry about avoiding
212           collisions with existing files; we take care of that in
213           find_unused_path().
214
215       output_prefix [PREFIX]
216           Instance method.  Get the short string that all filenames for
217           extracted body-parts will begin with (assuming that there is no
218           better "recommended filename").  The default is "msg".
219
220           If PREFIX is not given, the current output prefix is returned.  If
221           PREFIX is given, the output prefix is set to the new value, and the
222           previous value is returned.
223
224           Used by output_filename().
225
226           Note: subclasses of MIME::Parser::Filer which override
227           output_path() or output_filename() might not honor this setting;
228           note, however, that the built-in subclasses honor it.
229
230       output_type_ext
231           Instance method.  Return a reference to the hash used by the
232           default output_filename() for mapping from content-types to
233           extensions when there is no default extension to use.
234
235               $emap = $filer->output_typemap;
236               $emap->{'text/plain'} = '.txt';
237               $emap->{'text/html'}  = '.html';
238               $emap->{'text/*'}     = '.txt';
239               $emap->{'*/*'}        = '.dat';
240
241           Note: subclasses of MIME::Parser::Filer which override
242           output_path() or output_filename() might not consult this hash;
243           note, however, that the built-in subclasses consult it.
244
245       output_path HEAD
246           Instance method, subclasses only.  Given a MIME head for a file to
247           be extracted, come up with a good output pathname for the extracted
248           file.  This is the only method you need to worry about if you are
249           building a custom filer.
250
251           The default implementation does a lot of work; subclass
252           implementers really should try to just override its components
253           instead of the whole thing.  It works basically as follows:
254
255               $directory = $self->output_dir($head);
256
257               $filename = $head->recommended_filename();
258               if (!$filename or
259                    $self->ignore_filename() or
260                    $self->evil_filename($filename)) {
261                   $filename = $self->output_filename($head);
262               }
263
264               return $self->find_unused_path($directory, $filename);
265
266           Note: There are many, many, many ways you might want to control the
267           naming of files, based on your application.  If you don't like the
268           behavior of this function, you can easily define your own subclass
269           of MIME::Parser::Filer and override it there.
270
271           Note: Nickolay Saukh pointed out that, given the subjective nature
272           of what is "evil", this function really shouldn't warn about an
273           evil filename, but maybe just issue a debug message.  I considered
274           that, but then I thought: if debugging were off, people wouldn't
275           know why (or even if) a given filename had been ignored.  In mail
276           robots that depend on externally-provided filenames, this could
277           cause hard-to-diagnose problems.  So, the message is still a
278           warning.
279
280           Thanks to Laurent Amon for pointing out problems with the original
281           implementation, and for making some good suggestions.  Thanks also
282           to Achim Bohnet for pointing out that there should be a hookless,
283           OO way of overriding the output path.
284
285       purge
286           Instance method, final.  Purge all files/directories created by the
287           last parse.  This method simply goes through the purgeable list in
288           reverse order (see "purgeable") and removes all existing
289           files/directories in it.  You should not need to override this
290           method.
291
292       purgeable [FILE]
293           Instance method, final.  Add FILE to the list of "purgeable"
294           files/directories (those which will be removed if you do a
295           "purge()").  You should not need to override this method.
296
297           If FILE is not given, the "purgeable" list is returned.  This may
298           be used for more-sophisticated purging.
299
300           As a special case, invoking this method with a FILE that is an
301           arrayref will replace the purgeable list with a copy of the array's
302           contents, so [] may be used to clear the list.
303
304           Note that the "purgeable" list is cleared when a parser begins a
305           new parse; therefore, if you want to use purge() to do cleanup, you
306           must do so before starting a new parse!
307
308   MIME::Parser::FileInto
309       This concrete subclass of MIME::Parser::Filer supports filing into a
310       given directory.
311
312       init DIRECTORY
313           Instance method, initiallizer.  Set the directory where all files
314           will go.
315
316   MIME::Parser::FileUnder
317       This concrete subclass of MIME::Parser::Filer supports filing under a
318       given directory, using one subdirectory per message, but with all
319       message parts in the same directory.
320
321       init BASEDIR, OPTSHASH...
322           Instance method, initiallizer.  Set the base directory which will
323           contain the message directories.  If used, then each parse of
324           begins by creating a new subdirectory of BASEDIR where the actual
325           parts of the message are placed.  OPTSHASH can contain the
326           following:
327
328           DirName
329               Explicitly set the name of the subdirectory which is created.
330               The default is to use the time, process id, and a sequence
331               number, but you might want a predictable directory.
332
333           Purge
334               Automatically purge the contents of the directory (including
335               all subdirectories) before each parse.  This is really only
336               needed if using an explicit DirName, and is provided as a
337               convenience only.  Currently we use the 1-arg form of
338               File::Path::rmtree; you should familiarize yourself with the
339               caveats therein.
340
341           The output_dir() will return the path to this message-specific
342           directory until the next parse is begun, so you can do this:
343
344               use File::Path;
345
346               $parser->output_under("/tmp");
347               $ent = eval { $parser->parse_open($msg); };   ### parse
348               if (!$ent) {         ### parse failed
349                   rmtree($parser->output_dir);
350                   die "parse failed: $@";
351               }
352               else {               ### parse succeeded
353                   ...do stuff...
354               }
355

SEE ALSO

357       MIME::Tools, MIME::Parser
358

AUTHOR

360       Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).
361
362       All rights reserved.  This program is free software; you can
363       redistribute it and/or modify it under the same terms as Perl itself.
364
365
366
367perl v5.34.0                      2022-01-21            MIME::Parser::Filer(3)
Impressum