Devil Killer Is Here MiNi Shell
MiNi SheLL

Current Path : /proc/thread-self/root/usr/local/man/man3/
Linux boscustweb5004.eigbox.net 5.4.91 #1 SMP Wed Jan 20 18:10:28 EST 2021 x86_64
Current File : //proc/thread-self/root/usr/local/man/man3/MIME::Parser.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MIME::Parser 3"
.TH MIME::Parser 3 "2006-03-17" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
MIME::Parser \- experimental class for parsing MIME streams
.SH "SYNOPSIS"
.IX Header "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.
.PP
Ready?  Ok...
.Sh "Basic usage examples"
.IX Subsection "Basic usage examples"
.Vb 2
\&    ### Create a new parser object:
\&    my $parser = new MIME::Parser;
.Ve
.PP
.Vb 2
\&    ### Tell it where to put things:
\&    $parser->output_under("/tmp");
.Ve
.PP
.Vb 2
\&    ### Parse an input filehandle:
\&    $entity = $parser->parse(\e*STDIN);
.Ve
.PP
.Vb 2
\&    ### Congratulations: you now have a (possibly multipart) MIME entity!
\&    $entity->dump_skeleton;          # for debugging
.Ve
.Sh "Examples of input"
.IX Subsection "Examples of input"
.Vb 3
\&    ### Parse from filehandles:
\&    $entity = $parser->parse(\e*STDIN);
\&    $entity = $parser->parse(IO::File->new("some command|");
.Ve
.PP
.Vb 2
\&    ### Parse from any object that supports getline() and read():
\&    $entity = $parser->parse($myHandle);
.Ve
.PP
.Vb 2
\&    ### Parse an in-core MIME message:
\&    $entity = $parser->parse_data($message);
.Ve
.PP
.Vb 2
\&    ### Parse an MIME message in a file:
\&    $entity = $parser->parse_open("/some/file.msg");
.Ve
.PP
.Vb 2
\&    ### Parse an MIME message out of a pipeline:
\&    $entity = $parser->parse_open("gunzip - < file.msg.gz |");
.Ve
.PP
.Vb 2
\&    ### Parse already-split input (as "deliver" would give it to you):
\&    $entity = $parser->parse_two("msg.head", "msg.body");
.Ve
.Sh "Examples of output control"
.IX Subsection "Examples of output control"
.Vb 2
\&    ### Keep parsed message bodies in core (default outputs to disk):
\&    $parser->output_to_core(1);
.Ve
.PP
.Vb 2
\&    ### Output each message body to a one-per-message directory:
\&    $parser->output_under("/tmp");
.Ve
.PP
.Vb 2
\&    ### Output each message body to the same directory:
\&    $parser->output_dir("/tmp");
.Ve
.PP
.Vb 2
\&    ### Change how nameless message-component files are named:
\&    $parser->output_prefix("msg");
.Ve
.Sh "Examples of error recovery"
.IX Subsection "Examples of error recovery"
.Vb 6
\&    ### Normal mechanism:
\&    eval { $entity = $parser->parse(\e*STDIN) };
\&    if ($@) {
\&        $results  = $parser->results;
\&        $decapitated = $parser->last_head;  ### get last top-level head
\&    }
.Ve
.PP
.Vb 4
\&    ### Ultra-tolerant mechanism:
\&    $parser->ignore_errors(1);
\&    $entity = eval { $parser->parse(\e*STDIN) };
\&    $error = ($@ || $parser->last_error);
.Ve
.PP
.Vb 4
\&    ### Cleanup all files created by the parse:
\&    eval { $entity = $parser->parse(\e*STDIN) };
\&    ...
\&    $parser->filer->purge;
.Ve
.Sh "Examples of parser options"
.IX Subsection "Examples of parser options"
.Vb 2
\&    ### Automatically attempt to RFC-1522-decode the MIME headers?
\&    $parser->decode_headers(1);             ### default is false
.Ve
.PP
.Vb 2
\&    ### Parse contained "message/rfc822" objects as nested MIME streams?
\&    $parser->extract_nested_messages(0);    ### default is true
.Ve
.PP
.Vb 2
\&    ### Look for uuencode in "text" messages, and extract it?
\&    $parser->extract_uuencode(1);           ### default is false
.Ve
.PP
.Vb 2
\&    ### Should we forgive normally-fatal errors?
\&    $parser->ignore_errors(0);              ### default is true
.Ve
.Sh "Miscellaneous examples"
.IX Subsection "Miscellaneous examples"
.Vb 3
\&    ### Convert a Mail::Internet object to a MIME::Entity:
\&    @lines = (@{$mail->header}, "\en", @{$mail->body});
\&    $entity = $parser->parse_data(\e@lines);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
You can inherit from this class to create your own subclasses
that parse \s-1MIME\s0 streams into MIME::Entity objects.
.SH "PUBLIC INTERFACE"
.IX Header "PUBLIC INTERFACE"
.Sh "Construction"
.IX Subsection "Construction"
.IP "new \s-1ARGS\s0..." 4
.IX Item "new ARGS..."
\&\fIClass method.\fR
Create a new parser object.
Once you do this, you can then set up various parameters
before doing the actual parsing.  For example:
.Sp
.Vb 4
\&    my $parser = new MIME::Parser;
\&    $parser->output_dir("/tmp");
\&    $parser->output_prefix("msg1");
\&    my $entity = $parser->parse(\e*STDIN);
.Ve
.Sp
Any arguments are passed into \f(CW\*(C`init()\*(C'\fR.
Don't override this in your subclasses; override \fIinit()\fR instead.
.IP "init \s-1ARGS\s0..." 4
.IX Item "init ARGS..."
\&\fIInstance method.\fR
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.
.IP "init_parse" 4
.IX Item "init_parse"
\&\fIInstance method.\fR
Invoked automatically whenever one of the top-level \fIparse()\fR methods
is called, to reset the parser to a \*(L"ready\*(R" state.
.Sh "Altering how messages are parsed"
.IX Subsection "Altering how messages are parsed"
.IP "decode_headers [\s-1YESNO\s0]" 4
.IX Item "decode_headers [YESNO]"
\&\fIInstance method.\fR
Controls whether the parser will attempt to decode all the \s-1MIME\s0 headers
(as per \s-1RFC\-1522\s0) the moment it sees them.  \fBThis is not advisable
for two very important reasons:\fR
.RS 4
.IP "*" 4
\&\fBIt screws up the extraction of information from \s-1MIME\s0 fields.\fR
If you fully decode the headers into bytes, you can inadvertently
transform a parseable \s-1MIME\s0 header like this:
.Sp
.Vb 1
\&    Content-type: text/plain; filename="=?ISO-8859-1?Q?Hi=22Ho?="
.Ve
.Sp
into unparseable gobbledygook; in this case:
.Sp
.Vb 1
\&    Content-type: text/plain; filename="Hi"Ho"
.Ve
.IP "*" 4
\&\fBIt is information\-lossy.\fR  An encoded string which contains
both Latin\-1 and Cyrillic characters will be turned into a binary
mishmosh which simply can't be rendered.
.RE
.RS 4
.Sp
\&\fBHistory.\fR
This method was once the only out-of-the-box way to deal with attachments
whose filenames had non-ASCII characters.  However, since MIME-tools 5.4xx
this is no longer necessary.
.Sp
\&\fBParameters.\fR
If \s-1YESNO\s0 is true, decoding is done.  However, you will get a warning
unless you use one of the special \*(L"true\*(R" values:
.Sp
.Vb 3
\&   "I_NEED_TO_FIX_THIS"
\&          Just shut up and do it.  Not recommended.
\&          Provided only for those who need to keep old scripts functioning.
.Ve
.Sp
.Vb 3
\&   "I_KNOW_WHAT_I_AM_DOING"
\&          Just shut up and do it.  Not recommended.
\&          Provided for those who REALLY know what they are doing.
.Ve
.Sp
If \s-1YESNO\s0 is false (the default), no attempt at decoding will be done.
With no argument, just returns the current setting.
\&\fBRemember:\fR you can always decode the headers \fIafter\fR the parsing
has completed (see \fIMIME::Head::decode()\fR), or
decode the words on demand (see MIME::Words).
.RE
.IP "extract_nested_messages \s-1OPTION\s0" 4
.IX Item "extract_nested_messages OPTION"
\&\fIInstance method.\fR
Some \s-1MIME\s0 messages will contain a part of type \f(CW\*(C`message/rfc822\*(C'\fR
,\f(CW\*(C`message/partial\*(C'\fR or \f(CW\*(C`message/external\-body\*(C'\fR:
literally, the text of an embedded mail/news/whatever message.
This option controls whether (and how) we parse that embedded message.
.Sp
If the \s-1OPTION\s0 is false, we treat such a message just as if it were a
\&\f(CW\*(C`text/plain\*(C'\fR document, without attempting to decode its contents.
.Sp
If the \s-1OPTION\s0 is true (the default), the body of the \f(CW\*(C`message/rfc822\*(C'\fR
or \f(CW\*(C`message/partial\*(C'\fR part is parsed by this parser, creating an
entity object.  What happens then is determined by the actual \s-1OPTION:\s0
.RS 4
.IP "\s-1NEST\s0 or 1" 4
.IX Item "NEST or 1"
The default setting.
The contained message becomes the sole \*(L"part\*(R" of the \f(CW\*(C`message/rfc822\*(C'\fR
entity (as if the containing message were a special kind of
\&\*(L"multipart\*(R" message).
You can recover the sub-entity by invoking the \fIparts()\fR
method on the \f(CW\*(C`message/rfc822\*(C'\fR entity.
.IP "\s-1REPLACE\s0" 4
.IX Item "REPLACE"
The contained message replaces the \f(CW\*(C`message/rfc822\*(C'\fR entity, as though
the \f(CW\*(C`message/rfc822\*(C'\fR \*(L"container\*(R" never existed.
.Sp
\&\fBWarning:\fR notice that, with this option, all the header information
in the \f(CW\*(C`message/rfc822\*(C'\fR 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 subject line.  \f(CW\*(C`:\-/\*(C'\fR.
.RE
.RS 4
.Sp
\&\fIThanks to Andreas Koenig for suggesting this method.\fR
.RE
.IP "extract_uuencode [\s-1YESNO\s0]" 4
.IX Item "extract_uuencode [YESNO]"
\&\fIInstance method.\fR
If set true, then whenever we are confronted with a message
whose effective content-type is \*(L"text/plain\*(R" and whose encoding
is 7bit/8bit/binary, we scan the encoded body to see if it contains
uuencoded data (generally given away by a \*(L"begin \s-1XXX\s0\*(R" line).
.Sp
If it does, we explode the uuencoded message into a multipart,
where the text before the first \*(L"begin \s-1XXX\s0\*(R" becomes the first part,
and all \*(L"begin...end\*(R" sections following become the subsequent parts.
The filename (if given) is accessible through the normal means.
.IP "ignore_errors [\s-1YESNO\s0]" 4
.IX Item "ignore_errors [YESNO]"
\&\fIInstance method.\fR
Controls whether the parser will attempt to ignore normally-fatal
errors, treating them as warnings and continuing with the parse.
.Sp
If \s-1YESNO\s0 is true (the default), many syntax errors are tolerated.
If \s-1YESNO\s0 is false, fatal errors throw exceptions.
With no argument, just returns the current setting.
.IP "decode_bodies [\s-1YESNO\s0]" 4
.IX Item "decode_bodies [YESNO]"
\&\fIInstance method.\fR
Controls whether the parser should decode entity bodies or not.
If this is set to a false value (default is true), all entity bodies
will be kept as-is in the original content-transfer encoding.
.Sp
To prevent double encoding on the output side MIME::Body\->is_encoded
is set, which tells MIME::Body not to encode the data again, if encoded
data was requested. This is in particular useful, when it's important that
the content \fBmust not\fR be modified, e.g. if you want to calculate
OpenPGP signatures from it.
.Sp
\&\fB\s-1WARNING\s0\fR: the semantics change significantly if you parse \s-1MIME\s0
messages with this option set, because MIME::Entity resp. MIME::Body
*always* see encoded data now, while the default behaviour is
working with *decoded* data (and encoding it only if you request it).
You need to decode the data yourself, if you want to have it decoded.
.Sp
So use this option only if you exactly know, what you're doing, and
that you're sure, that you really need it.
.Sh "Parsing an input source"
.IX Subsection "Parsing an input source"
.IP "parse_data \s-1DATA\s0" 4
.IX Item "parse_data DATA"
\&\fIInstance method.\fR
Parse a \s-1MIME\s0 message that's already in core.
You may supply the \s-1DATA\s0 in any of a number of ways...
.RS 4
.IP "*" 4
\&\fBA scalar\fR which holds the message.
.IP "*" 4
\&\fBA ref to a scalar\fR which holds the message.  This is an efficiency hack.
.IP "*" 4
\&\fBA ref to an array of scalars.\fR  They are treated as a stream
which (conceptually) consists of simply concatenating the scalars.
.RE
.RS 4
.Sp
Returns the parsed MIME::Entity on success.
.RE
.IP "parse \s-1INSTREAM\s0" 4
.IX Item "parse INSTREAM"
\&\fIInstance method.\fR
Takes a MIME-stream and splits it into its component entities.
.Sp
The \s-1INSTREAM\s0 can be given as a readable FileHandle, an IO::File,
a globref filehandle (like \f(CW\*(C`\e*STDIN\*(C'\fR),
or as \fIany\fR blessed object conforming to the \s-1IO::\s0 interface
(which minimally implements \fIgetline()\fR and \fIread()\fR).
.Sp
Returns the parsed MIME::Entity on success.
Throws exception on failure.  If the message contained too many
parts (as set by \fImax_parts\fR), returns undef.
.IP "parse_open \s-1EXPR\s0" 4
.IX Item "parse_open EXPR"
\&\fIInstance method.\fR
Convenience front-end onto \f(CW\*(C`parse()\*(C'\fR.
Simply give this method any expression that may be sent as the second
argument to \fIopen()\fR to open a filehandle for reading.
.Sp
Returns the parsed MIME::Entity on success.
Throws exception on failure.
.IP "parse_two \s-1HEADFILE\s0, \s-1BODYFILE\s0" 4
.IX Item "parse_two HEADFILE, BODYFILE"
\&\fIInstance method.\fR
Convenience front-end onto \f(CW\*(C`parse_open()\*(C'\fR, intended for programs
running under mail-handlers like \fBdeliver\fR, which splits the incoming
mail message into a header file and a body file.
Simply give this method the paths to the respective files.
.Sp
\&\fBWarning:\fR 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.
.Sp
\&\fBWarning:\fR new implementation slurps files into line array
for portability, instead of using 'cat'.  May be an issue if
your messages are large.
.Sp
Returns the parsed MIME::Entity on success.
Throws exception on failure.
.Sh "Specifying output destination"
.IX Subsection "Specifying output destination"
\&\fBWarning:\fR 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.)
.PP
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.
.PP
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.
.IP "filer [\s-1FILER\s0]" 4
.IX Item "filer [FILER]"
\&\fIInstance method.\fR
Get/set the \s-1FILER\s0 object used to manage the output of files to disk.
This will be some subclass of MIME::Parser::Filer.
.IP "output_dir \s-1DIRECTORY\s0" 4
.IX Item "output_dir DIRECTORY"
\&\fIInstance method.\fR
Causes messages to be filed directly into the given \s-1DIRECTORY\s0.
It does this by setting the underlying \fIfiler()\fR to
a new instance of MIME::Parser::FileInto, and passing the arguments
into that class' \fInew()\fR method.
.Sp
\&\fBNote:\fR Since this method replaces the underlying
filer, you must invoke it \fIbefore\fR doing changing any attributes
of the filer, like the output prefix; otherwise those changes
will be lost.
.IP "output_under \s-1BASEDIR\s0, \s-1OPTS\s0..." 4
.IX Item "output_under BASEDIR, OPTS..."
\&\fIInstance method.\fR
Causes messages to be filed directly into subdirectories of the given
\&\s-1BASEDIR\s0, one subdirectory per message.  It does this by setting the
underlying \fIfiler()\fR to a new instance of MIME::Parser::FileUnder,
and passing the arguments into that class' \fInew()\fR method.
.Sp
\&\fBNote:\fR Since this method replaces the underlying
filer, you must invoke it \fIbefore\fR doing changing any attributes
of the filer, like the output prefix; otherwise those changes
will be lost.
.IP "output_path \s-1HEAD\s0" 4
.IX Item "output_path HEAD"
\&\fIInstance method, \s-1DEPRECATED\s0.\fR
Given a \s-1MIME\s0 head for a file to be extracted, come up with a good
output pathname for the extracted file.
Identical to the preferred form:
.Sp
.Vb 1
\&     $parser->filer->output_path(...args...);
.Ve
.Sp
We just delegate this to the underlying \fIfiler()\fR object.
.IP "output_prefix [\s-1PREFIX\s0]" 4
.IX Item "output_prefix [PREFIX]"
\&\fIInstance method, \s-1DEPRECATED\s0.\fR
Get/set the short string that all filenames for extracted body-parts
will begin with (assuming that there is no better \*(L"recommended filename\*(R").
Identical to the preferred form:
.Sp
.Vb 1
\&     $parser->filer->output_prefix(...args...);
.Ve
.Sp
We just delegate this to the underlying \fIfiler()\fR object.
.IP "evil_filename \s-1NAME\s0" 4
.IX Item "evil_filename NAME"
\&\fIInstance method, \s-1DEPRECATED\s0.\fR
Identical to the preferred form:
.Sp
.Vb 1
\&     $parser->filer->evil_filename(...args...);
.Ve
.Sp
We just delegate this to the underlying \fIfiler()\fR object.
.IP "max_parts \s-1NUM\s0" 4
.IX Item "max_parts NUM"
\&\fIInstance method.\fR
Limits the number of \s-1MIME\s0 parts we will parse.
.Sp
Normally, instances of this class parse a message to the bitter end.
Messages with many \s-1MIME\s0 parts can cause excessive memory consumption.
If you invoke this method, parsing will abort with a \fIdie()\fR if a message
contains more than \s-1NUM\s0 parts.
.Sp
If \s-1NUM\s0 is set to \-1 (the default), then no maximum limit is enforced.
.Sp
With no argument, returns the current setting as an integer
.IP "output_to_core \s-1YESNO\s0" 4
.IX Item "output_to_core YESNO"
\&\fIInstance method.\fR
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:
.Sp
If \s-1YESNO\s0 is false (the default), then all body data goes
to disk files.
.Sp
If \s-1YESNO\s0 is true, then all body data goes to in-core data structures
This is a little risky (what if someone emails you an \s-1MPEG\s0 or a tar
file, hmmm?) but people seem to want this bit of noose-shaped rope,
so I'm providing it.
Note that setting this attribute true \fIdoes not\fR mean that parser-internal
temporary files are avoided!  Use \fItmp_to_core()\fR for that.
.Sp
With no argument, returns the current setting as a boolean.
.IP "tmp_recycling [\s-1YESNO\s0]" 4
.IX Item "tmp_recycling [YESNO]"
\&\fIInstance method.\fR
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.
.Sp
If \s-1YESNO\s0 is true (the default), we allow recycling;
tmpfiles persist until the parser itself is destroyed.
If \s-1YESNO\s0 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.
.IP "tmp_to_core [\s-1YESNO\s0]" 4
.IX Item "tmp_to_core [YESNO]"
\&\fIInstance method.\fR
Should \fInew_tmpfile()\fR 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.
.Sp
If \s-1YESNO\s0 is true, we implement \fInew_tmpfile()\fR via in-core handles.
If \s-1YESNO\s0 is false (the default), we use real tmpfiles.
With no argument, just returns the current setting.
.IP "use_inner_files [\s-1YESNO\s0]" 4
.IX Item "use_inner_files [YESNO]"
\&\fIInstance method.\fR
If you are parsing from a handle which supports \fIseek()\fR and \fItell()\fR,
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.
.Sp
If \s-1YESNO\s0 is false (the default), then we will not use IO::InnerFile.
If \s-1YESNO\s0 is true, we use IO::InnerFile if we can.
With no argument, just returns the current setting.
.Sp
\&\fBNote:\fR inner files are slower than \fIreal\fR tmpfiles,
but possibly faster than \fIin-core\fR tmpfiles... so your choice for
this option will probably depend on your choice for
\&\fItmp_to_core()\fR and the kind of input streams you are
parsing.
.Sh "Specifying classes to be instantiated"
.IX Subsection "Specifying classes to be instantiated"
.IP "interface \s-1ROLE\s0,[\s-1VALUE\s0]" 4
.IX Item "interface ROLE,[VALUE]"
\&\fIInstance method.\fR
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 \*(L"head\*(R" class may provide some additional MIME-field-oriented methods).
.Sp
If so, then this is the method that your subclass should invoke during
init.  Use it like this:
.Sp
.Vb 10
\&    package MyParser;
\&    @ISA = qw(MIME::Parser);
\&    ...
\&    sub init {
\&        my $self = shift;
\&        $self->SUPER::init(@_);        ### do my parent's init
\&        $self->interface(ENTITY_CLASS => 'MIME::MyEntity');
\&        $self->interface(HEAD_CLASS   => 'MIME::MyHead');
\&        $self;                         ### return
\&    }
.Ve
.Sp
With no \s-1VALUE\s0, returns the \s-1VALUE\s0 currently associated with that \s-1ROLE\s0.
.IP "new_body_for \s-1HEAD\s0" 4
.IX Item "new_body_for HEAD"
\&\fIInstance method.\fR
Based on the \s-1HEAD\s0 of a part we are parsing, return a new
body object (any desirable subclass of MIME::Body) for
receiving that part's data.
.Sp
If you set the \f(CW\*(C`output_to_core\*(C'\fR option to false before parsing
(the default), then we call \f(CW\*(C`output_path()\*(C'\fR and create a
new MIME::Body::File on that filename.
.Sp
If you set the \f(CW\*(C`output_to_core\*(C'\fR option to true before parsing,
then you get a MIME::Body::InCore instead.
.Sp
If you want the parser to do something else entirely, you can
override this method in a subclass.
.IP "new_tmpfile [\s-1RECYCLE\s0]" 4
.IX Item "new_tmpfile [RECYCLE]"
\&\fIInstance method.\fR
Return an \s-1IO\s0 handle to be used to hold temporary data during a parse.
The default uses the standard IO::File\->\fInew_tmpfile()\fR method unless
\&\fItmp_to_core()\fR dictates otherwise, but you can override this.
You shouldn't need to.
.Sp
If you do override this, make certain that the object you return is
set for \fIbinmode()\fR, and is able to handle the following methods:
.Sp
.Vb 6
\&    read(BUF, NBYTES)
\&    getline()
\&    getlines()
\&    print(@ARGS)
\&    flush()
\&    seek(0, 0)
.Ve
.Sp
Fatal exception if the stream could not be established.
.Sp
If \s-1RECYCLE\s0 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 support
recycling, just ignore it and always return a new object.
.Sh "Parse results and error recovery"
.IX Subsection "Parse results and error recovery"
.IP "last_error" 4
.IX Item "last_error"
\&\fIInstance method.\fR
Return the error (if any) that we ignored in the last parse.
.IP "last_head" 4
.IX Item "last_head"
\&\fIInstance method.\fR
Return the top-level \s-1MIME\s0 header of the last stream we attempted to parse.
This is useful for replying to people who sent us bad \s-1MIME\s0 messages.
.Sp
.Vb 6
\&    ### Parse an input stream:
\&    eval { $entity = $parser->parse(\e*STDIN) };
\&    if (!$entity) {    ### parse failed!
\&        my $decapitated = $parser->last_head;
\&        ...
\&    }
.Ve
.IP "results" 4
.IX Item "results"
\&\fIInstance method.\fR
Return an object containing lots of info from the last entity parsed.
This will be an instance of class
MIME::Parser::Results.
.SH "OPTIMIZING YOUR PARSER"
.IX Header "OPTIMIZING YOUR PARSER"
.Sh "Maximizing speed"
.IX Subsection "Maximizing speed"
Optimum input mechanisms:
.PP
.Vb 5
\&    parse()                    YES (if you give it a globref or a
\&                                    subclass of IO::File)
\&    parse_open()               YES
\&    parse_data()               NO  (see below)
\&    parse_two()                NO  (see below)
.Ve
.PP
Optimum settings:
.PP
.Vb 8
\&    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)
.Ve
.PP
\&\fBFile I/O is much faster than in-core I/O.\fR
Although it \fIseems\fR 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 operating-system calls, whereas the in-core I/O is
implemented in Perl.
.PP
\&\fBInner files are slower than real tmpfiles, but faster than in-core ones.\fR
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.
.PP
\&\fBNative I/O is much faster than object-oriented I/O.\fR
It's much faster to use <$foo> than \f(CW$foo\fR\->getline.
For backwards compatibilty, this module must continue to use
object-oriented I/O in most places, but if you use \fIparse()\fR
with a \*(L"real\*(R" filehandle (string, globref, or subclass of IO::File)
then MIME::Parser is able to perform some crucial optimizations.
.PP
\&\fBThe \f(BIparse_two()\fB call is very inefficient.\fR
Currently this is just a front-end onto \fIparse_data()\fR.
If your \s-1OS\s0 supports it, you're \fIfar\fR better off doing something like:
.PP
.Vb 1
\&    $parser->parse_open("/bin/cat msg.head msg.body |");
.Ve
.Sh "Minimizing memory"
.IX Subsection "Minimizing memory"
Optimum input mechanisms:
.PP
.Vb 4
\&    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)
.Ve
.PP
Optimum settings:
.PP
.Vb 9
\&    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)
.Ve
.Sh "Maximizing tolerance of bad \s-1MIME\s0"
.IX Subsection "Maximizing tolerance of bad MIME"
Optimum input mechanisms:
.PP
.Vb 4
\&    parse()                    *** (doesn't matter)
\&    parse_open()               *** (doesn't matter)
\&    parse_data()               *** (doesn't matter)
\&    parse_two()                *** (doesn't matter)
.Ve
.PP
Optimum settings:
.PP
.Vb 7
\&    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)
.Ve
.Sh "Avoiding disk-based temporary files"
.IX Subsection "Avoiding disk-based temporary files"
Optimum input mechanisms:
.PP
.Vb 4
\&    parse()                    YES (if you give it a seekable 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))
.Ve
.PP
Optimum settings:
.PP
.Vb 6
\&    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
.Ve
.PP
\&\fBIf we can use them, inner files avoid most tmpfiles.\fR
If you parse from a seekable-and-tellable filehandle, then the internal
\&\fIprocess_to_bound()\fR doesn't need to extract each part into a temporary
buffer; it can use IO::InnerFile (\fBwarning:\fR this will slow down
the parsing of messages with large attachments).
.PP
\&\fBYou can veto tmpfiles entirely.\fR
If you might not be parsing from a seekable-and-tellable filehandle,
you can set \fItmp_to_core()\fR true: this will always
use in-core I/O for the buffering (\fBwarning:\fR this will slow down
the parsing of messages with large attachments).
.PP
\&\fBFinal resort.\fR
You can always override \fInew_tmpfile()\fR in a subclass.
.SH "WARNINGS"
.IX Header "WARNINGS"
.IP "Multipart messages are always read line-by-line" 4
.IX Item "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 \s-1MIME\s0
composition agents (for example, naive \s-1CGI\s0 scripts) might return
multipart documents where the parts are, say, unencoded bitmap
files... and, consequently, where such \*(L"lines\*(R" might be
veeeeeeeeery long indeed.
.Sp
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.
.IP "Multipart parts read into temp files before decoding" 4
.IX Item "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 \s-1MIME\s0 documents.
While this decode-while-parsing approach obviated the need for
temporary files, it resulted in inflexible and complex decoder
implementations.
.Sp
The revised implementation uses a temporary file (a la \f(CW\*(C`tmpfile()\*(C'\fR)
during parsing to hold the \fIencoded\fR portion of the current \s-1MIME\s0
document or part.  This file is deleted automatically after the
current part is decoded and the data is written to the \*(L"body stream\*(R"
object; you'll never see it, and should never need to worry about it.
.Sp
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 accomodating this wish, but the temp-file
approach solves a lot of thorny problems in parsing, and it also
protects against hidden bugs in user applications (what if you've
directed the encoded part into a scalar, and someone unexpectedly
sends you a 6 \s-1MB\s0 tar file?).  Finally, I'm just not conviced that
the temp-file use adds significant overhead.
.IP "Fuzzing of \s-1CRLF\s0 and newline on input" 4
.IX Item "Fuzzing of CRLF and newline on input"
\&\s-1RFC\-1521\s0 dictates that \s-1MIME\s0 streams have lines terminated by \s-1CRLF\s0
(\f(CW"\er\en"\fR).  However, it is extremely likely that folks will want to
parse \s-1MIME\s0 streams where each line ends in the local newline
character \f(CW"\en"\fR instead.
.Sp
An attempt has been made to allow the parser to handle both \s-1CRLF\s0
and newline-terminated input.
.IP "Fuzzing of \s-1CRLF\s0 and newline on output" 4
.IX Item "Fuzzing of CRLF and newline on output"
The \f(CW"7bit"\fR and \f(CW"8bit"\fR decoders will decode both
a \f(CW"\en"\fR and a \f(CW"\er\en"\fR end-of-line sequence into a \f(CW"\en"\fR.
.Sp
The \f(CW"binary"\fR decoder (default if no encoding specified)
still outputs stuff verbatim... so a \s-1MIME\s0 message with CRLFs
and no explicit encoding will be output as a text file
that, on many systems, will have an annoying ^M at the end of
each line... \fIbut this is as it should be\fR.
.IP "Inability to handle multipart boundaries that contain newlines" 4
.IX Item "Inability to handle multipart boundaries that contain newlines"
First, let's get something straight: \fIthis is an evil, \s-1EVIL\s0 practice,\fR
and is incompatible with \s-1RFC\-1521\s0... hence, it's not valid \s-1MIME\s0.
.Sp
If your mailer creates multipart boundary strings that contain
newlines \fIwhen they appear in the message body,\fR give it two weeks notice
and find another one.  If your mail robot receives \s-1MIME\s0 mail like this,
regard it as syntactically incorrect \s-1MIME\s0, which it is.
.Sp
Why do I say that?  Well, in \s-1RFC\-1521\s0, the syntax of a boundary is
given quite clearly:
.Sp
.Vb 1
\&      boundary := 0*69<bchars> bcharsnospace
.Ve
.Sp
.Vb 1
\&      bchars := bcharsnospace / " "
.Ve
.Sp
.Vb 2
\&      bcharsnospace :=    DIGIT / ALPHA / "'" / "(" / ")" / "+" /"_"
\&                   / "," / "-" / "." / "/" / ":" / "=" / "?"
.Ve
.Sp
All of which means that a valid boundary string \fIcannot\fR have
newlines in it, and any newlines in such a string in the message header
are expected to be solely the result of \fIfolding\fR the string (i.e.,
inserting to-be-removed newlines for readability and line-shortening
\&\fIonly\fR).
.Sp
Yet, there is at least one brain-damaged user agent out there
that composes mail like this:
.Sp
.Vb 4
\&      MIME-Version: 1.0
\&      Content-type: multipart/mixed; boundary="----ABC-
\&       123----"
\&      Subject: Hi... I'm a dork!
.Ve
.Sp
.Vb 1
\&      This is a multipart MIME message (yeah, right...)
.Ve
.Sp
.Vb 2
\&      ----ABC-
\&       123----
.Ve
.Sp
.Vb 1
\&      Hi there!
.Ve
.Sp
We have \fIgot\fR to discourage practices like this (and the recent file
upload idiocy where binary files that are part of a multipart \s-1MIME\s0
message aren't base64\-encoded) if we want \s-1MIME\s0 to stay relatively
simple, and \s-1MIME\s0 parsers to be relatively robust.
.Sp
\&\fIThanks to Andreas Koenig for bringing a baaaaaaaaad user agent to
my attention.\fR
.SH "AUTHOR"
.IX Header "AUTHOR"
Eryq (\fIeryq@zeegee.com\fR), ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
David F. Skoll (dfs@roaringpenguin.com) http://www.roaringpenguin.com
.PP
All rights reserved.  This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.SH "VERSION"
.IX Header "VERSION"
$Revision: 1.20 $ \f(CW$Date:\fR 2006/03/17 21:03:23 $
Creat By MiNi SheLL
Email: devilkiller@gmail.com