mime::parser(3)

NAME

MIME::Parser - experimental class for parsing MIME streams

SYNOPSIS

Before reading further, you should see MIME::Tools 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...
Basic usage examples
    ### Create a new parser object:
    my $parser = new MIME::Parser;
    ### Tell it where to put things:
    $parser->output_under("/tmp");
    ### Parse an input filehandle:
    $entity = $parser->parse(TDIN);
    ### Congratulations: you now have a  (possibly  multipart) MIME entity!
    $entity->dump_skeleton;          # for debugging
Examples of input
    ### Parse from filehandles:
    $entity = $parser->parse(TDIN);
    $entity   =   $parser->parse(IO::File->new("some  command|");
    ### Parse from any object that supports getline()  and
read():
    $entity = $parser->parse($myHandle);
    ### Parse an in-core MIME message:
    $entity = $parser->parse_data($message);
    ### Parse an MIME message in a file:
    $entity = $parser->parse_open("/some/file.msg");
    ### Parse an MIME message out of a pipeline:
    $entity  = $parser->parse_open("gunzip - < file.msg.gz
|");
    ### Parse already-split input (as "deliver" would give
it to you):
    $entity = $parser->parse_two("msg.head", "msg.body");
Examples of output control
    ###  Keep  parsed message bodies in core (default outputs to disk):
    $parser->output_to_core(1);
    ### Output each message body to a one-per-message  directory:
    $parser->output_under("/tmp");
    ### Output each message body to the same directory:
    $parser->output_dir("/tmp");
    ###  Change  how  nameless message-component files are
named:
    $parser->output_prefix("msg");
Examples of error recovery
    ### Normal mechanism:
    eval { $entity = $parser->parse(TDIN) };
    if ($@) {
        $results  = $parser->results;
        $decapitated = $parser->last_head;  ###  get  last
top-level head
    }
    ### Ultra-tolerant mechanism:
    $parser->ignore_errors(1);
    $entity = eval { $parser->parse(TDIN) };
    $error = ($@ || $parser->last_error);
    ### Cleanup all files created by the parse:
    eval { $entity = $parser->parse(TDIN) };
    ...
    $parser->filer->purge;
Examples of parser options
    ###  Automatically attempt to RFC-1522-decode the MIME
headers?
    $parser->decode_headers(1);             ### default is
false
    ### Parse contained "message/rfc822" objects as nested
MIME streams?
    $parser->extract_nested_messages(0);    ### default is
true
    ###  Look for uuencode in "text" messages, and extract
it?
    $parser->extract_uuencode(1);           ### default is
false
    ### Should we forgive normally-fatal errors?
    $parser->ignore_errors(0);              ### default is
true
Miscellaneous examples
    ### Convert a Mail::Internet object to a MIME::Entity:
    @lines = (@{$mail->header}, "0, @{$mail->body});
    $entity = $parser->parse_data(@lines);

DESCRIPTION

You can inherit from this class to create your own sub
classes that parse MIME streams into MIME::Entity objects.

PUBLIC INTERFACE

Construction

new ARGS...: Class method. Create a new parser object. Once you do this, you can then set up various parameters before
doing the actual parsing. For example:

my $parser = new MIME::Parser;
$parser->output_dir("/tmp");
$parser->output_prefix("msg1");
my $entity = $parser->parse(TDIN);; Any arguments are passed into "init()". Don't over
ride this in your subclasses; override init() instead.
init ARGS...: Instance method. Initiallize a new MIME::Parser object. This is automatically sent to a new object;
you may want to override it. If you override this, be
sure to invoke the inherited method.
init_parse: Instance method. Invoked automatically whenever one of the top-level parse() methods is called, to reset the parser to a "ready" state.
Altering how messages are parsed
decode_headers [YESNO]: Instance method. Controls whether the parser will attempt to decode all the MIME headers (as per
RFC-1522) the moment it sees them. This is not advis able for two very important reasons:; � It screws up the extraction of information from
MIME fields. If you fully decode the headers into bytes, you can inadvertently transform a parseable
MIME header like this:

Content-type: text/plain; file

name="=?ISO-8859-1?Q?Hi=22Ho?="

into unparseable gobbledygook; in this case:

Content-type: text/plain; filename="Hi"Ho"
� It is information-lossy. An encoded string which: contains both Latin-1 and Cyrillic characters will
be turned into a binary mishmosh which simply
can't be rendered.
History. This method was once the only out-of-the-box way to deal with attachments whose filenames had nonASCII characters. However, since MIME-tools 5.4xx
this is no longer necessary.
Parameters. If YESNO is true, decoding is done. How ever, you will get a warning unless you use one of the
special "true" values:: "I_NEED_TO_FIX_THIS"
Just shut up and do it. Not recommended.
Provided only for those who need to keep old

scripts functioning.; "I_KNOW_WHAT_I_AM_DOING"
Just shut up and do it. Not recommended.
Provided for those who REALLY know what they

are doing.
If YESNO is false (the default), no attempt at decod
ing will be done. With no argument, just returns the
current setting. Remember: you can always decode the headers after the parsing has completed (see
MIME::Head::decode()), or decode the words on demand (see MIME::Words).
extract_nested_messages OPTION: Instance method. Some MIME messages will contain a part of type "message/rfc822": literally, the text of
an embedded mail/news/whatever message. This option
controls whether (and how) we parse that embedded mes
sage.; If the OPTION is false, we treat such a message just
as if it were a "text/plain" document, without
attempting to decode its contents.; If the OPTION is true (the default), the body of the
"message/rfc822" part is parsed by this parser, creat
ing an entity object. What happens then is determined
by the actual OPTION:; NEST or 1
The default setting. The contained message
becomes the sole "part" of the "message/rfc822"
entity (as if the containing message were a spe
cial kind of "multipart" message). You can
recover the sub-entity by invoking the parts()
method on the "message/rfc822" entity.; REPLACE
The contained message replaces the "mes
sage/rfc822" entity, as though the "mes
sage/rfc822" "container" never existed.

Warning: notice that, with this option, all the header information in the "message/rfc822" header
is lost. This might seriously bother you if
you're dealing with a top-level message, and
you've just lost the sender's address and the sub
ject line. ":-/".; Thanks to Andreas Koenig for suggesting this method.
extract_uuencode [YESNO]: Instance method. If set true, then whenever we are confronted with a message whose effective content-type
is "text/plain" and whose encoding is
7bit/8bit/binary, we scan the encoded body to see if
it contains uuencoded data (generally given away by a
"begin XXX" line).; If it does, we explode the uuencoded message into a
multipart, where the text before the first "begin XXX"
becomes the first part, and all "begin...end" sections
following become the subsequent parts. The filename
(if given) is accessible through the normal means.
ignore_errors [YESNO]: Instance method. Controls whether the parser will attempt to ignore normally-fatal errors, treating them
as warnings and continuing with the parse.; If YESNO is true (the default), many syntax errors are
tolerated. If YESNO is false, fatal errors throw
exceptions. With no argument, just returns the cur
rent setting.
Parsing an input source
parse_data DATA: Instance method. Parse a MIME message that's already in core. You may supply the DATA in any of a number
of ways...; � A scalar which holds the message.; � A ref to a scalar which holds the message. This
is an efficiency hack.; � A ref to an array of scalars. They are treated as
a stream which (conceptually) consists of simply
concatenating the scalars.; Returns the parsed MIME::Entity on success. Throws
exception on failure.
parse INSTREAM: Instance method. Takes a MIME-stream and splits it into its component entities.; The INSTREAM can be given as a readable FileHandle, an
IO::File, a globref filehandle (like "TDIN"), or as
any blessed object conforming to the IO:: interface
(which minimally implements getline() and read()).; Returns the parsed MIME::Entity on success. Throws
exception on failure.
parse_open EXPR: Instance method. Convenience front-end onto "parse()". Simply give this method any expression
that may be sent as the second argument to open() to
open a filehandle for reading.; Returns the parsed MIME::Entity on success. Throws
exception on failure.
parse_two HEADFILE, BODYFILE: Instance method. Convenience front-end onto "parse_open()", intended for programs running under
mail-handlers like deliver, which splits the incoming mail message into a header file and a body file. Sim
ply give this method the paths to the respective
files.; Warning: it is assumed that, once the files are cat'ed together, there will be a blank line separating the
head part and the body part.; Warning: new implementation slurps files into line array for portability, instead of using 'cat'. May be
an issue if your messages are large.; Returns the parsed MIME::Entity on success. Throws
exception on failure.
Specifying output destination
Warning: in 5.212 and before, this was done by methods of MIME::Parser. However, since many users have requested
fine-tuned control over how this is done, the logic has
been split off from the parser into its own class,
MIME::Parser::Filer Every MIME::Parser maintains an
instance of a MIME::Parser::Filer subclass to manage disk
output (see MIME::Parser::Filer for details.)
The benefit to this is that the MIME::Parser code won't be confounded with a lot of garbage related to disk output. The drawback is that the way you override the default behavior will change.
For now, all the normal public-interface methods are still provided, but many are only stubs which create or delegate to the underlying MIME::Parser::Filer object.
filer [FILER]: Instance method. Get/set the FILER object used to manage the output of files to disk. This will be some
subclass of MIME::Parser::Filer.
output_dir DIRECTORY: Instance method. Causes messages to be filed directly into the given DIRECTORY. It does this by setting the
underlying filer() to a new instance of
MIME::Parser::FileInto, and passing the arguments into
that class' new() method.; Note: Since this method replaces the underlying filer,
you must invoke it before doing changing any
attributes of the filer, like the output prefix; oth
erwise those changes will be lost.
output_under BASEDIR, OPTS...: Instance method. Causes messages to be filed directly into subdirectories of the given BASEDIR, one subdi
rectory per message. It does this by setting the
underlying filer() to a new instance of
MIME::Parser::FileUnder, and passing the arguments
into that class' new() method.; Note: Since this method replaces the underlying filer,
you must invoke it before doing changing any
attributes of the filer, like the output prefix; oth
erwise those changes will be lost.
output_path HEAD: Instance method, DEPRECATED. Given a MIME head for a file to be extracted, come up with a good output path
name for the extracted file. Identical to the pre
ferred form:

$parser->filer->output_path(...args...);; We just delegate this to the underlying filer()
object.
output_prefix [PREFIX]: Instance method, DEPRECATED. Get/set the short string that all filenames for extracted body-parts will begin
with (assuming that there is no better "recommended
filename"). Identical to the preferred form:

$parser->filer->output_prefix(...args...);; We just delegate this to the underlying filer()
object.
evil_filename NAME: Instance method, DEPRECATED. Identical to the pre ferred form:

$parser->filer->evil_filename(...args...);; We just delegate this to the underlying filer()
object.
output_to_core YESNO: Instance method. Normally, instances of this class output all their decoded body data to disk files (via
MIME::Body::File). However, you can change this
behaviour by invoking this method before parsing:; If YESNO is false (the default), then all body data
goes to disk files.; If YESNO is true, then all body data goes to in-core
data structures This is a little risky (what if some
one emails you an MPEG or a tar file, hmmm?) but peo
ple seem to want this bit of noose-shaped rope, so I'm
providing it. Note that setting this attribute true
does not mean that parser-internal temporary files are avoided! Use tmp_to_core() for that.; With no argument, returns the current setting as a
boolean.
tmp_recycling [YESNO]: Instance method. Normally, tmpfiles are created when needed during parsing, and destroyed automatically
when they go out of scope. But for efficiency, you
might prefer for your parser to attempt to rewind and
reuse the same file until the parser itself is
destroyed.; If YESNO is true (the default), we allow recycling;
tmpfiles persist until the parser itself is destroyed.
If YESNO is false, we do not allow recycling; tmpfiles
persist only as long as they are needed during the
parse. With no argument, just returns the current
setting.
tmp_to_core [YESNO]: Instance method. Should new_tmpfile() create real temp files, or use fake in-core ones? Normally we
allow the creation of temporary disk files, since this
allows us to handle huge attachments even when core is
limited.; If YESNO is true, we implement new_tmpfile() via incore handles. If YESNO is false (the default), we use
real tmpfiles. With no argument, just returns the
current setting.
use_inner_files [YESNO]: Instance method. If you are parsing from a handle which supports seek() and tell(), then we can avoid tmpfiles completely by using IO::InnerFile, if so
desired: basically, we simulate a temporary file via
pointers to virtual start- and end-positions in the
input stream.; If YESNO is false (the default), then we will not use
IO::InnerFile. If YESNO is true, we use IO::InnerFile
if we can. With no argument, just returns the current
setting.; Note: inner files are slower than real tmpfiles, but possibly faster than in-core tmpfiles... so your
choice for this option will probably depend on your
choice for tmp_to_core() and the kind of input streams you are parsing.
Specifying classes to be instantiated
interface ROLE,[VALUE]: Instance method. During parsing, the parser normally creates instances of certain classes, like
MIME::Entity. However, you may want to create a
parser subclass that uses your own experimental head,
entity, etc. classes (for example, your "head" class
may provide some additional MIME-field-oriented meth
ods).; If so, then this is the method that your subclass
should invoke during init. Use it like this:

package MyParser;
@ISA = qw(MIME::Parser);
...
sub init {
my $self = shift;
$self->SUPER::init(@_); ### do my par

ent's init
$self->interface(ENTITY_CLASS => 'MIME::MyEn

tity');
$self->interface(HEAD_CLASS => 'MIME::My

Head');
$self; ### return

}; With no VALUE, returns the VALUE currently associated
with that ROLE.
new_body_for HEAD: Instance method. Based on the HEAD of a part we are parsing, return a new body object (any desirable sub
class of MIME::Body) for receiving that part's data.; If you set the "output_to_core" option to false before
parsing (the default), then we call "output_path()"
and create a new MIME::Body::File on that filename.; If you set the "output_to_core" option to true before
parsing, then you get a MIME::Body::InCore instead.; If you want the parser to do something else entirely,
you can override this method in a subclass.
new_tmpfile [RECYCLE]: Instance method. Return an IO handle to be used to hold temporary data during a parse. The default uses
the standard IO::File->new_tmpfile() method unless tmp_to_core() dictates otherwise, but you can override this. You shouldn't need to.; If you do override this, make certain that the object
you return is set for binmode(), and is able to handle the following methods:

read(BUF, NBYTES)
getline()
getlines()
print(@ARGS)
flush()
seek(0, 0); Fatal exception if the stream could not be estab
lished.; If RECYCLE is given, it is an object returned by a
previous invocation of this method; to recycle it,
this method must effectively rewind and truncate it,
and return the same object. If you don't want to sup
port recycling, just ignore it and always return a new
object.
Parse results and error recovery
last_error: Instance method. Return the error (if any) that we ignored in the last parse.
last_head: Instance method. Return the top-level MIME header of the last stream we attempted to parse. This is useful
for replying to people who sent us bad MIME messages.

### Parse an input stream:
eval { $entity = $parser->parse(TDIN) };
if (!$entity) { ### parse failed!
my $decapitated = $parser->last_head;
...

}
results: Instance method. Return an object containing lots of info from the last entity parsed. This will be an
instance of class MIME::Parser::Results.

OPTIMIZING YOUR PARSER

Maximizing speed

Optimum input mechanisms:: parse() YES (if you give it a glo; bref or a
subclass of IO::File); parse_open() YES
parse_data() NO (see below)
parse_two() NO (see below)
Optimum settings:: decode_headers() *** (no real difference; 0; is slightly faster)
extract_nested_messages() 0 (may be slightly; faster, but in
general you want it

set to 1); output_to_core() 0 (will be MUCH faster)
tmp_recycling() 1? (probably, but should; be investigated)
tmp_to_core() 0 (will be MUCH faster)
use_inner_files() 0 (if tmp_to_core() is 0;
use 1 otherwise)
File I/O is much faster than in-core I/O. Although it seems like slurping a message into core and processing it
in-core should be faster... it isn't. Reason: Perl's
filehandle-based I/O translates directly into native oper
ating-system calls, whereas the in-core I/O is implemented
in Perl.
Inner files are slower than real tmpfiles, but faster than in-core ones. If speed is your concern, that's why you should set use_inner_files(true) if you set
tmp_to_core(true): so that we can bypass the slow in-core
tmpfiles if the input stream permits.
Native I/O is much faster than object-oriented I/O. It's much faster to use <$foo> than $foo->getline. For back
wards compatibilty, this module must continue to use
object-oriented I/O in most places, but if you use parse() with a "real" filehandle (string, globref, or subclass of
IO::File) then MIME::Parser is able to perform some
crucial optimizations.
The ppaarrssee__ttwwoo(()) call is very inefficient. Currently this is just a front-end onto parse_data(). If your OS sup ports it, you're far better off doing something like:: $parser->parse_open("/bin/cat msg.head msg.body |");
Minimizing memory
Optimum input mechanisms:: parse() YES
parse_open() YES
parse_data() NO (in-core I/O will burn; core)
parse_two() NO (in-core I/O will burn; core)
Optimum settings:: decode_headers() *** (no real difference)
extract_nested_messages() *** (no real difference)
output_to_core() 0 (will use MUCH less; memory)
tmp_recycling() 0? (promotes faster GC if
tmp_to_core is 1); tmp_to_core() 0 (will use MUCH less; memory)
use_inner_files() *** (no real difference,; but set it to 1
if you *must* have

tmp_to_core set to 1,
so that you avoid in

core tmpfiles)
Maximizing tolerance of bad MIME
Optimum input mechanisms:: parse() *** (doesn't matter)
parse_open() *** (doesn't matter)
parse_data() *** (doesn't matter)
parse_two() *** (doesn't matter)
Optimum settings:: decode_headers() 0 (sidesteps problem of; bad hdr encodings)
extract_nested_messages() 0 (sidesteps problems of; bad nested messages,
but often you want it

set to 1 anyway).; output_to_core() *** (doesn't matter)
tmp_recycling() *** (doesn't matter)
tmp_to_core() *** (doesn't matter)
use_inner_files() *** (doesn't matter)
Avoiding disk-based temporary files
Optimum input mechanisms:: parse() YES (if you give it a seek; able handle)
parse_open() YES (becomes a seekable; handle)
parse_data() NO (unless you set; tmp_to_core(1))
parse_two() NO (unless you set; tmp_to_core(1))
Optimum settings:: decode_headers() *** (doesn't matter)
extract_nested_messages() *** (doesn't matter)
output_to_core() *** (doesn't matter)
tmp_recycling 1 (restricts created; files to 1 per parser)
tmp_to_core() 1
use_inner_files() 1
If we can use them, inner files avoid most tmpfiles. If you parse from a seekable-and-tellable filehandle, then
the internal process_to_bound() doesn't need to extract each part into a temporary buffer; it can use IO::Inner
File (warning: this will slow down the parsing of messages with large attachments).
You can veto tmpfiles entirely. If you might not be pars ing from a seekable-and-tellable filehandle, you can set
tmp_to_core() true: this will always use in-core I/O for the buffering (warning: this will slow down the parsing of messages with large attachments).
Final resort. You can always override new_tmpfile() in a subclass.

WARNINGS

Multipart messages are always read line-by-line: Multipart document parts are read line-by-line, so
that the encapsulation boundaries may easily be
detected. However, bad MIME composition agents (for
example, naive CGI scripts) might return multipart
documents where the parts are, say, unencoded bitmap
files... and, consequently, where such "lines" might
be veeeeeeeeery long indeed.; A better solution for this case would be to set up
some form of state machine for input processing. This
will be left for future versions.
Multipart parts read into temp files before decoding: In my original implementation, the MIME::Decoder
classes had to be aware of encapsulation boundaries in
multipart MIME documents. While this decode-whileparsing approach obviated the need for temporary
files, it resulted in inflexible and complex decoder
implementations.; The revised implementation uses a temporary file (a la
"tmpfile()") during parsing to hold the encoded por
tion of the current MIME document or part. This file
is deleted automatically after the current part is
decoded and the data is written to the "body stream"
object; you'll never see it, and should never need to
worry about it.; Some folks have asked for the ability to bypass this
temp-file mechanism, I suppose because they assume it
would slow down their application. I considered acco
modating this wish, but the temp-file approach solves
a lot of thorny problems in parsing, and it also pro
tects against hidden bugs in user applications (what
if you've directed the encoded part into a scalar, and
someone unexpectedly sends you a 6 MB tar file?).
Finally, I'm just not conviced that the temp-file use
adds significant overhead.
Fuzzing of CRLF and newline on input: RFC-1521 dictate0).haHowever,titais extremelys termi nated by CRLF ("
likely that folks will want to parse MIME streams
where each line ends in the local newline character
"0 instead.; An attempt has been made to allow the parser to handle
both CRLF and newline-terminated input.
Fuzzing of CRLF and newline on output: The "7b0tend-of-line"sequencesintolad"0.de both a "0 and a "; The "binary" decoder (default if no encoding speci
fied) still outputs stuff verbatim... so a MIME mes
sage with CRLFs and no explicit encoding will be out
put as a text file that, on many systems, will have an
annoying ^M at the end of each line... but this is as it should be.
Inability to handle multipart boundaries that contain new lines: First, let's get something straight: this is an evil, EVIL practice, and is incompatible with RFC-1521... hence, it's not valid MIME.; If your mailer creates multipart boundary strings that
contain newlines when they appear in the message body, give it two weeks notice and find another one. If
your mail robot receives MIME mail like this, regard
it as syntactically incorrect MIME, which it is.; Why do I say that? Well, in RFC-1521, the syntax of a
boundary is given quite clearly:

boundary := 0*69<bchars> bcharsnospace

bchars := bcharsnospace / " "

bcharsnospace := DIGIT / ALPHA / "'" / "(" /

")" / "+" /"_"
/ "," / "-" / "." / "/" / ":" / "="

/ "?"
All of which means that a valid boundary string cannot have newlines in it, and any newlines in such a string in the message header are expected to be solely the result of folding the string (i.e., inserting to-beremoved newlines for readability and line-shortening only).
Yet, there is at least one brain-damaged user agent out there that composes mail like this:: MIME-Version: 1.0
Content-type: multipart/mixed; bound; ary="----ABC
123----"; Subject: Hi... I'm a dork!; This is a multipart MIME message (yeah,; right...); ----ABC
123---; Hi there!
We have got to discourage practices like this (and the recent file upload idiocy where binary files that are part of a multipart MIME message aren't base64-encoded) if we want MIME to stay relatively simple, and MIME parsers to be relatively robust.
Thanks to Andreas Koenig for bringing a baaaaaaaaad user agent to my attention.

AUTHOR

Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).

VERSION

$Revision: 5.406 $ $Date: 2000/11/12 05:55:11 $

docs.sk

komplexný repozitár dokumentácie

V sekcií