Opcje wyszukiwania podręcznika man:
Lista stron man zaczynających się od znaku:
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z   ALPHA   NUM   OTHER   ALL
MIME::Parser(3pm)     User Contributed Perl Documentation    MIME::Parser(3pm)

       MIME::Parser - experimental class for parsing MIME streams

       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:

           ### Parse an input filehandle:
           $entity = $parser->parse(\*STDIN);

           ### Congratulations: you now have a (possibly multipart) MIME entity!
           $entity->dump_skeleton;          # for debugging

   Examples of input
           ### Parse from filehandles:
           $entity = $parser->parse(\*STDIN);
           $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):

           ### Output each message body to a one-per-message directory:

           ### Output each message body to the same directory:

           ### Change how nameless message-component files are named:

           ### Put temporary files somewhere else

   Examples of error recovery
           ### Normal mechanism:
           eval { $entity = $parser->parse(\*STDIN) };
           if ($@) {
               $results  = $parser->results;
               $decapitated = $parser->last_head;  ### get last top-level head

           ### Ultra-tolerant mechanism:
           $entity = eval { $parser->parse(\*STDIN) };
           $error = ($@ || $parser->last_error);

           ### Cleanup all files created by the parse:
           eval { $entity = $parser->parse(\*STDIN) };

   Examples of parser options
           ### Automatically attempt to RFC 2047-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:
           my $data = join('', (@{$mail->header}, "\n", @{$mail->body}));
           $entity = $parser->parse_data(\$data);

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

       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;
               my $entity = $parser->parse(\*STDIN);

           Any arguments are passed into "init()".  Don't override 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.

           Instance method.  Invoked automatically whenever one of the top-
           level parse() methods is called, to reset the parser to a "ready"

   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 2047) the moment it sees
           them.  This is not advisable for two very important reasons:

           o   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; filename="=?ISO-8859-1?Q?Hi=22Ho?="

               into unparseable gobbledygook; in this case:

                   Content-type: text/plain; filename="Hi"Ho"

           o   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 non-ASCII characters.
           However, since MIME-tools 5.4xx this is no longer necessary.

           Parameters.  If YESNO is true, decoding is done.  However, you will
           get a warning unless you use one of the special "true" values:

                     Just shut up and do it.  Not recommended.
                     Provided only for those who need to keep old scripts functioning.

                     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 decoding 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" ,"message/partial" or "message/external-body":
           literally, the text of an embedded mail/news/whatever message.
           This option controls whether (and how) we parse that embedded

           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" or "message/partial" part is parsed by this
           parser, creating 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 special kind of "multipart" message).  You can
               recover the sub-entity by invoking the parts() method on the
               "message/rfc822" entity.

               The contained message replaces the "message/rfc822" entity, as
               though the "message/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
               subject 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"

           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

       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 current setting.

       decode_bodies [YESNO]
           Instance method.  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.

           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 must not be
           modified, e.g. if you want to calculate OpenPGP signatures from it.

           WARNING: the semantics change significantly if you parse MIME
           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.

           So use this option only if you exactly know, what you're doing, and
           that you're sure, that you really need it.

   Parsing an input source
       parse_data DATA
           Instance method.  Parse a MIME message that's already in core.
           This internally creates an "in memory" filehandle on a Perl scalar
           value using PerlIO

           You may supply the DATA in any of a number of ways...

           o   A scalar which holds the message.  A reference to this scalar
               will be used internally.

           o   A ref to a scalar which holds the message.  This reference will
               be used internally.

           o   DEPRECATED

               A ref to an array of scalars.  The array is internally
               concatenated into a temporary string, and a reference to the
               new string is used internally.

               It is much more efficient to pass in a scalar reference, so
               please consider refactoring your code to use that interface
               instead.  If you absolutely MUST pass an array, you may be
               better off using IO::ScalarArray in the calling code to
               generate a filehandle, and passing that filehandle to parse()

           Returns the parsed MIME::Entity on success.

       parse INSTREAM
           Instance method.  Takes a MIME-stream and splits it into its
           component entities.

           The INSTREAM can be given as an IO::File, a globref filehandle
           (like "\*STDIN"), 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.  If the message contained too many parts (as set by
           max_parts), returns undef.

       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

       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.  Simply give this method the paths to the respective

           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

           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

   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

       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; otherwise those changes will be lost.

       output_under BASEDIR, OPTS...
           Instance method.  Causes messages to be filed directly into
           subdirectories of the given BASEDIR, one subdirectory 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; otherwise 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 pathname for the extracted
           file.  Identical to the preferred form:


           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:


           We just delegate this to the underlying filer() object.

       evil_filename NAME
           Instance method, DEPRECATED.  Identical to the preferred form:


           We just delegate this to the underlying filer() object.

       max_parts NUM
           Instance method.  Limits the number of MIME parts we will parse.

           Normally, instances of this class parse a message to the bitter
           end.  Messages with many MIME parts can cause excessive memory
           consumption.  If you invoke this method, parsing will abort with a
           die() if a message contains more than NUM parts.

           If NUM is set to -1 (the default), then no maximum limit is

           With no argument, returns the current setting as an integer

       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

           If YESNO is true, then all body data goes to in-core data
           structures This is a little 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.  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.

           Instance method, DEPRECATED.

           This method is a no-op to preserve the pre-5.421 API.

           The tmp_recycling() feature was removed in 5.421 because it had
           never actually worked.  Please update your code to stop using it.

       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 in-core 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.

           MIME::Parser no longer supports IO::InnerFile, but this method is
           retained for backwards compatibility.  It does nothing.

           The original reasoning for IO::InnerFile was that inner files were
           faster than "in-core" temp files.  At the time, the "in-core"
           tempfile support was implemented with IO::Scalar from the IO-
           Stringy distribution, which used the tie() interface to wrap a
           scalar with the appropriate IO::Handle operations.  The penalty for
           this was fairly hefty, and IO::InnerFile actually was faster.

           Nowadays, MIME::Parser uses Perl's built in ability to open a
           filehandle on an in-memory scalar variable via PerlIO.
           Benchmarking shows that IO::InnerFile is slightly slower than using
           in-memory temporary files, and is slightly faster than on-disk
           temporary files.  Both measurements are within a few percent of
           each other.  Since there's no real benefit, and since the
           IO::InnerFile abuse was fairly hairy and evil ("writes" to it were
           faked by extending the size of the inner file with the assumption
           that the only data you'd ever ->print() to it would be the line
           from the "outer" file, for example) it's been removed.

   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 methods).

           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 parent's init
                   $self->interface(ENTITY_CLASS => 'MIME::MyEntity');
                   $self->interface(HEAD_CLASS   => 'MIME::MyHead');
                   $self;                         ### return

           With no VALUE, returns the VALUE currently associated with that

       new_body_for HEAD
           Instance method.  Based on the HEAD of a part we are parsing,
           return a new body object (any desirable subclass 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.

   Temporary File Creation
       tmp_dir DIRECTORY
           Instance method.  Causes any temporary files created by this parser
           to be created in the given DIRECTORY.

           If called without arguments, returns current value.

           The default value is undef, which will cause new_tmpfile() to use
           the system default temporary directory.

           Instance method.  Return an IO handle to be used to hold temporary
           data during a parse.

           The default uses MIME::Tools::tmpopen() to create a new temporary
           file, unless tmp_to_core() dictates otherwise, but you can override
           this.  You shouldn't need to.

           The location for temporary files can be changed on a per-parser
           basis with tmp_dir().

           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)
               seek(0, 0)

           Fatal exception if the stream could not be established.

   Parse results and error recovery
           Instance method.  Return the error (if any) that we ignored in the
           last parse.

           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(\*STDIN) };
               if (!$entity) {    ### parse failed!
                   my $decapitated = $parser->last_head;

           Instance method.  Return an object containing lots of info from the
           last entity parsed.  This will be an instance of class

   Maximizing speed
       Optimum input mechanisms:

           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)

       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_to_core()              0   (will be MUCH faster)

       Native I/O is much faster than object-oriented I/O.  It's much faster
       to use <$foo> than $foo->getline.  For backwards compatibility, 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

       The parse_two() call is very inefficient.  Currently this is just a
       front-end onto parse_data().  If your OS supports 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_to_core is 1)
           tmp_to_core()              0   (will use MUCH less memory)

   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_to_core()              *** (doesn't matter)

   Avoiding disk-based temporary files
       Optimum input mechanisms:

           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))

       Optimum settings:

           decode_headers()           *** (doesn't matter)
           extract_nested_messages()  *** (doesn't matter)
           output_to_core()           *** (doesn't matter)
           tmp_to_core()              1

       You can veto tmpfiles entirely.  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.

       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

       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-while-parsing approach obviated the need for
           temporary files, it resulted in inflexible and complex decoder

           The revised implementation uses a temporary file (a la "tmpfile()")
           during parsing to hold the encoded portion 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 accommodating 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 MB tar file?).  Finally, I'm just not
           convinced that the temp-file use adds significant overhead.

       Fuzzing of CRLF and newline on input
           RFC 2045 dictates that MIME streams have lines terminated by CRLF
           ("\r\n").  However, it is extremely likely that folks will want to
           parse MIME streams where each line ends in the local newline
           character "\n" 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 "7bit" and "8bit" decoders will decode both a "\n" and a "\r\n"
           end-of-line sequence into a "\n".

           The "binary" decoder (default if no encoding specified) still
           outputs stuff verbatim... so a MIME 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... but
           this is as it should be.

       Inability to handle multipart boundaries that contain newlines
           First, let's get something straight: this is an evil, EVIL
           practice, and is incompatible with RFC 2046... 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 2046, 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-be-removed 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; boundary="----ABC-
                 Subject: Hi... I'm a dork!

                 This is a multipart MIME message (yeah, right...)


                 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.

       MIME::Tools, MIME::Head, MIME::Body, MIME::Entity, MIME::Decoder

       Eryq (, ZeeGee Software Inc (
       David F. Skoll (

       All rights reserved.  This program is free software; you can
       redistribute it and/or modify it under the same terms as Perl itself.

perl v5.18.1                      2013-11-14                 MIME::Parser(3pm)

Czas wygenerowania: 0.00016 sek.

Created with the man page lookup class by Andrew Collington.
Based on a C man page viewer by Vadim Pavlov
Unicode soft-hyphen fix (as used by RedHat) by Dan Edwards
Some optimisations by Eli Argon
Caching idea and code contribution by James Richardson

Copyright © 2003-2023
Hosted by Hosting