1MIME::Parser::Filer(3)User Contributed Perl DocumentationMIME::Parser::Filer(3)
2
6 MIME::Parser::Filer - manage file-output of the parser
7
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 Ready? Ok... now read "DESCRIPTION" below, and everything else should
14 make sense.
15 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 ### Want added security? Don't let outsiders name your files:
23 $filer->ignore_filename(1);
24 ### Prepare for the parsing of a new top-level message:
26 $filer->init_parse;
27 ### Return the path where this message's data should be placed:
29 $path = $filer->output_path($head);
30 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 ### Tweak the mapping from content-type to extension:
36 $emap = $filer->output_extension_map;
37 $emap->{"text/html"} = ".htm";
38
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 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 $filer = $parser->filer;
49 At the beginning of each "parse()", the filer's internal state is reset
51 by the parser:
52 $parser->filer->init_parse;
54 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 $new_file = $parser->filer->output_path($head);
60 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 $parser->filer->purgeable($new_file);
66 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 $parser->filer->purge;
72 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 The only method you have to override is output_path():
81 $filer->output_path($head);
83 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 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 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 $dir = $filer->output_dir($head);
98 $name = $filer->output_filename($head);
99 ...
100
102 MIME::Parser::Filer
103 This is the abstract superclass of all "filer" objects.
104 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 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 init_parse
117 Instance method. Prepare to start parsing a new message.
118 Subclasses should always be sure to invoke the inherited method.
119 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 * 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 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 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 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 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 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 Returns the exorcised filename (which is guaranteed to not be
158 evil), or undef if it could not be salvaged.
159 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 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 The suffix is actually added before the first "." in the filename
175 is there is one; for example:
176 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 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 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 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 output_dir HEAD
201 Instance method. Return the output directory for the given header.
202 The default method returns ".".
203 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 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 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 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 Used by output_filename().
225 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 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 $emap = $filer->output_typemap;
236 $emap->{'text/plain'} = '.txt';
237 $emap->{'text/html'} = '.html';
238 $emap->{'text/*'} = '.txt';
239 $emap->{'*/*'} = '.dat';
240 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 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 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 $directory = $self->output_dir($head);
256 $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 return $self->find_unused_path($directory, $filename);
265 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 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 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 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 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 If FILE is not given, the "purgeable" list is returned. This may
298 be used for more-sophisticated purging.
299 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 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 MIME::Parser::FileInto
309 This concrete subclass of MIME::Parser::Filer supports filing into a
310 given directory.
311 init DIRECTORY
313 Instance method, initiallizer. Set the directory where all files
314 will go.
315 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 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 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 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 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 use File::Path;
345 $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
357 MIME::Tools, MIME::Parser
358
360 Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).
361 All rights reserved. This program is free software; you can
363 redistribute it and/or modify it under the same terms as Perl itself.
364perl v5.34.0 2021-07-22 MIME::Parser::Filer(3)