MIME::Tools | MIME::Body | MIME::Decoder | MIME::Entity |
MIME::Head | MIME::IO | MIME::Latin1 | MIME::Parser |
MIME::ParserBase | MIME::ToolUtils | MIME::Tools | MIME::Words |
MIME:: |
MIME::Parser - split MIME mail into decoded components
# Create a new parser object: my $parser = new MIME::Parser;
# Set up output directory for files: $parser->output_dir("$ENV{HOME}/mimemail");
# Set up the prefix for files with auto-generated names: $parser->output_prefix("part");
# If content length is <= 20000 bytes, store each msg as in-core scalar; # Else, write to a disk file (the default action): $parser->output_to_core(20000);
# Parse an input stream: $entity = $parser->read(\*STDIN) or die "couldn't parse MIME stream";
# Congratulations: you now have a (possibly multipart) MIME entity! $entity->dump_skeleton; # for debugging
Shortcuts:
# Create a new parser object, and set some properties: my $parser = new MIME::Parser output_dir => "$ENV{HOME}/mimemail", output_prefix => "part", output_to_core => 20000;
A subclass of MIME::ParserBase, providing one useful way to parse MIME streams and obtain MIME::Entity objects. This particular parser class outputs the different parts as files on disk, in the directory of your choice.
If you don't like the way files are named... it's object-oriented and subclassable. If you want to do something really different, perhaps you want to subclass MIME::ParserBase instead.
For example:
$p = new MIME::Parser output_dir => "/tmp/mime", output_to_core => 'ALL';
"/"
characters,
or if it's "."
, ".."
, or empty.
Override this method in a subclass if you just want to change which externally-provided filenames are allowed, and which are not. Like this:
package MIME::MyParser;
use MIME::Parser; @ISA = qw(MIME::Parser);
sub evil_filename { my ($self, $name) = @_; return ($name !~ /^[a-z\d][a-z\d\._-]*$/i); # only simple names ok }
Note: This method used to be a lot stricter, but it unnecessailry inconvenienced users on non-ASCII systems. That has been changed in 4.x.
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.
The default behavior is to examine the HEAD for a recommended
filename (generating a random one if none is available),
and create a new MIME::Body::File on that filename in
the parser's current output_dir()
.
If you use the output_to_core
method (q.v.) before parsing,
you can force this method to output some or all or a message's
parts to in-core data structures, based on their size.
If you want the parser to do something else entirely, you should override this method in a subclass.
"."
.
If DIRECTORY
is not given, the current output directory is returned.
If DIRECTORY
is given, the output directory is set to the new value,
and the previous value is returned.
Note: this is used by the output_path()
method in this class.
It should also be used by subclasses, but if a subclass decides to
output parts in some completely different manner, this method may
of course be completely ignored.
The "directory" portion of the returned path will be the output_dir()
,
and the "filename" portion will be determined as follows:
output_prefix()
,
will be used.
Note: If you don't like the behavior of this function, you can define your own subclass of MIME::Parser and override it there:
package MIME::MyParser;
require 5.002; # for SUPER use package MIME::Parser;
@MIME::MyParser::ISA = ('MIME::Parser');
sub output_path { my ($self, $head) = @_;
# Your code here; FOR EXAMPLE... if (i_have_a_preference) { return my_custom_path; } else { # return the default path: return $self->SUPER::output_path($head); } } 1;
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, but now it's only output if $^W is true.
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.
If PREFIX
is not given, the current output prefix is returned.
If PREFIX
is given, the output directory is set to the new value,
and the previous value is returned.
If CUTOFF is an integer, then we examine the Content-length
of
each entity being parsed. If the content-length is known to be
CUTOFF or below, the body data will go to an in-core data structure;
If the content-length is unknown or if it exceeds CUTOFF, then
the body data will go to a disk file.
If the CUTOFF is the string "NONE", then all body data goes to disk files regardless of the content-length. This is the default behaviour.
If the CUTOFF is the string "ALL", then all body data goes to in-core data structures regardless of the content-length. This is very risky (what if someone emails you an MPEG or a tar file, hmmm?) but people seem to want this bit of noose-shaped rope, so I'm providing it.
Without argument, returns the current cutoff: "ALL", "NONE" (the default), or a number.
See the new_body_for()
method for more details.
Authors of subclasses can consider overriding the following methods. They are listed in approximate order of most-to-least impact.
Copyright (c) 1997 by Eryq / eryq@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.
$Revision: 4.102 $ $Date: 1997/12/14 03:04:10 $