{ "content": [ { "type": "text", "text": "# MIME::Parser (perldoc)\n\n## NAME\n\nMIME::Parser - experimental class for parsing MIME streams\n\n## SYNOPSIS\n\nBefore reading further, you should see MIME::Tools to make sure that you understand where this\nmodule fits into the grand scheme of things. Go on, do it now. I'll wait.\nReady? Ok...\n\n## DESCRIPTION\n\nYou can inherit from this class to create your own subclasses that parse MIME streams into\nMIME::Entity objects.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS** (6 subsections)\n- **DESCRIPTION**\n- **PUBLIC INTERFACE** (7 subsections)\n- **OPTIMIZING YOUR PARSER** (4 subsections)\n- **WARNINGS**\n- **SEE ALSO**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "MIME::Parser", "section": "", "mode": "perldoc", "summary": "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\nmodule fits into the grand scheme of things. Go on, do it now. I'll wait.\nReady? Ok...", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 5, "subsections": [ { "name": "Basic usage examples", "lines": 12 }, { "name": "Examples of input", "lines": 19 }, { "name": "Examples of output control", "lines": 15 }, { "name": "Examples of error recovery", "lines": 17 }, { "name": "Examples of parser options", "lines": 12 }, { "name": "Miscellaneous examples", "lines": 4 } ] }, { "name": "DESCRIPTION", "lines": 3, "subsections": [] }, { "name": "PUBLIC INTERFACE", "lines": 1, "subsections": [ { "name": "Construction", "lines": 21 }, { "name": "Altering how messages are parsed", "lines": 101 }, { "name": "Parsing an input source", "lines": 52 }, { "name": "Specifying output destination", "lines": 122 }, { "name": "Specifying classes to be instantiated", "lines": 35 }, { "name": "Temporary File Creation", "lines": 29 }, { "name": "Parse results and error recovery", "lines": 18 } ] }, { "name": "OPTIMIZING YOUR PARSER", "lines": 1, "subsections": [ { "name": "Maximizing speed", "lines": 26 }, { "name": "Minimizing memory", "lines": 15 }, { "name": "Maximizing tolerance of bad MIME", "lines": 15 }, { "name": "Avoiding disk-based temporary files", "lines": 19 } ] }, { "name": "WARNINGS", "lines": 84, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "AUTHOR", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "MIME::Parser - experimental class for parsing MIME streams\n", "subsections": [] }, "SYNOPSIS": { "content": "Before reading further, you should see MIME::Tools to make sure that you understand where this\nmodule fits into the grand scheme of things. Go on, do it now. I'll wait.\n\nReady? Ok...\n", "subsections": [ { "name": "Basic usage examples", "content": "### Create a new parser object:\nmy $parser = new MIME::Parser;\n\n### Tell it where to put things:\n$parser->outputunder(\"/tmp\");\n\n### Parse an input filehandle:\n$entity = $parser->parse(\\*STDIN);\n\n### Congratulations: you now have a (possibly multipart) MIME entity!\n$entity->dumpskeleton; # for debugging\n" }, { "name": "Examples of input", "content": "### Parse from filehandles:\n$entity = $parser->parse(\\*STDIN);\n$entity = $parser->parse(IO::File->new(\"some command|\");\n\n### Parse from any object that supports getline() and read():\n$entity = $parser->parse($myHandle);\n\n### Parse an in-core MIME message:\n$entity = $parser->parsedata($message);\n\n### Parse an MIME message in a file:\n$entity = $parser->parseopen(\"/some/file.msg\");\n\n### Parse an MIME message out of a pipeline:\n$entity = $parser->parseopen(\"gunzip - < file.msg.gz |\");\n\n### Parse already-split input (as \"deliver\" would give it to you):\n$entity = $parser->parsetwo(\"msg.head\", \"msg.body\");\n" }, { "name": "Examples of output control", "content": "### Keep parsed message bodies in core (default outputs to disk):\n$parser->outputtocore(1);\n\n### Output each message body to a one-per-message directory:\n$parser->outputunder(\"/tmp\");\n\n### Output each message body to the same directory:\n$parser->outputdir(\"/tmp\");\n\n### Change how nameless message-component files are named:\n$parser->outputprefix(\"msg\");\n\n### Put temporary files somewhere else\n$parser->tmpdir(\"/var/tmp/mytmpdir\");\n" }, { "name": "Examples of error recovery", "content": "### Normal mechanism:\neval { $entity = $parser->parse(\\*STDIN) };\nif ($@) {\n$results = $parser->results;\n$decapitated = $parser->lasthead; ### get last top-level head\n}\n\n### Ultra-tolerant mechanism:\n$parser->ignoreerrors(1);\n$entity = eval { $parser->parse(\\*STDIN) };\n$error = ($@ || $parser->lasterror);\n\n### Cleanup all files created by the parse:\neval { $entity = $parser->parse(\\*STDIN) };\n...\n$parser->filer->purge;\n" }, { "name": "Examples of parser options", "content": "### Automatically attempt to RFC 2047-decode the MIME headers?\n$parser->decodeheaders(1); ### default is false\n\n### Parse contained \"message/rfc822\" objects as nested MIME streams?\n$parser->extractnestedmessages(0); ### default is true\n\n### Look for uuencode in \"text\" messages, and extract it?\n$parser->extractuuencode(1); ### default is false\n\n### Should we forgive normally-fatal errors?\n$parser->ignoreerrors(0); ### default is true\n" }, { "name": "Miscellaneous examples", "content": "### Convert a Mail::Internet object to a MIME::Entity:\nmy $data = join('', (@{$mail->header}, \"\\n\", @{$mail->body}));\n$entity = $parser->parsedata(\\$data);\n" } ] }, "DESCRIPTION": { "content": "You can inherit from this class to create your own subclasses that parse MIME streams into\nMIME::Entity objects.\n", "subsections": [] }, "PUBLIC INTERFACE": { "content": "", "subsections": [ { "name": "Construction", "content": "new ARGS...\n*Class method.* Create a new parser object. Once you do this, you can then set up various\nparameters before doing the actual parsing. For example:\n\nmy $parser = new MIME::Parser;\n$parser->outputdir(\"/tmp\");\n$parser->outputprefix(\"msg1\");\nmy $entity = $parser->parse(\\*STDIN);\n\nAny arguments are passed into \"init()\". Don't override this in your subclasses; override\ninit() instead.\n\ninit ARGS...\n*Instance method.* Initiallize a new MIME::Parser object. This is automatically sent to a\nnew object; you may want to override it. If you override this, be sure to invoke the\ninherited method.\n\ninitparse\n*Instance method.* Invoked automatically whenever one of the top-level parse() methods is\ncalled, to reset the parser to a \"ready\" state.\n" }, { "name": "Altering how messages are parsed", "content": "decodeheaders [YESNO]\n*Instance method.* Controls whether the parser will attempt to decode all the MIME headers\n(as per RFC 2047) the moment it sees them. This is not advisable for two very important\nreasons:\n\n* It screws up the extraction of information from MIME fields. If you fully decode the\nheaders into bytes, you can inadvertently transform a parseable MIME header like this:\n\nContent-type: text/plain; filename=\"=?ISO-8859-1?Q?Hi=22Ho?=\"\n\ninto unparseable gobbledygook; in this case:\n\nContent-type: text/plain; filename=\"Hi\"Ho\"\n\n* It is information-lossy. An encoded string which contains both Latin-1 and Cyrillic\ncharacters will be turned into a binary mishmosh which simply can't be rendered.\n\nHistory. This method was once the only out-of-the-box way to deal with attachments whose\nfilenames had non-ASCII characters. However, since MIME-tools 5.4xx this is no longer\nnecessary.\n\nParameters. If YESNO is true, decoding is done. However, you will get a warning unless you\nuse one of the special \"true\" values:\n\n\"INEEDTOFIXTHIS\"\nJust shut up and do it. Not recommended.\nProvided only for those who need to keep old scripts functioning.\n\n\"IKNOWWHATIAMDOING\"\nJust shut up and do it. Not recommended.\nProvided for those who REALLY know what they are doing.\n\nIf YESNO is false (the default), no attempt at decoding will be done. With no argument, just\nreturns the current setting. Remember: you can always decode the headers *after* the parsing\nhas completed (see MIME::Head::decode()), or decode the words on demand (see MIME::Words).\n\nextractnestedmessages OPTION\n*Instance method.* Some MIME messages will contain a part of type \"message/rfc822\"\n,\"message/partial\" or \"message/external-body\": literally, the text of an embedded\nmail/news/whatever message. This option controls whether (and how) we parse that embedded\nmessage.\n\nIf the OPTION is false, we treat such a message just as if it were a \"text/plain\" document,\nwithout attempting to decode its contents.\n\nIf the OPTION is true (the default), the body of the \"message/rfc822\" or \"message/partial\"\npart is parsed by this parser, creating an entity object. What happens then is determined by\nthe actual OPTION:\n\nNEST or 1\nThe default setting. The contained message becomes the sole \"part\" of the\n\"message/rfc822\" entity (as if the containing message were a special kind of \"multipart\"\nmessage). You can recover the sub-entity by invoking the parts() method on the\n\"message/rfc822\" entity.\n\nREPLACE\nThe contained message replaces the \"message/rfc822\" entity, as though the\n\"message/rfc822\" \"container\" never existed.\n\nWarning: notice that, with this option, all the header information in the\n\"message/rfc822\" header is lost. This might seriously bother you if you're dealing with\na top-level message, and you've just lost the sender's address and the subject line.\n\":-/\".\n\n*Thanks to Andreas Koenig for suggesting this method.*\n\nextractuuencode [YESNO]\n*Instance method.* If set true, then whenever we are confronted with a message whose\neffective content-type is \"text/plain\" and whose encoding is 7bit/8bit/binary, we scan the\nencoded body to see if it contains uuencoded data (generally given away by a \"begin XXX\"\nline).\n\nIf it does, we explode the uuencoded message into a multipart, where the text before the\nfirst \"begin XXX\" becomes the first part, and all \"begin...end\" sections following become\nthe subsequent parts. The filename (if given) is accessible through the normal means.\n\nignoreerrors [YESNO]\n*Instance method.* Controls whether the parser will attempt to ignore normally-fatal errors,\ntreating them as warnings and continuing with the parse.\n\nIf YESNO is true (the default), many syntax errors are tolerated. If YESNO is false, fatal\nerrors throw exceptions. With no argument, just returns the current setting.\n\ndecodebodies [YESNO]\n*Instance method.* Controls whether the parser should decode entity bodies or not. If this\nis set to a false value (default is true), all entity bodies will be kept as-is in the\noriginal content-transfer encoding.\n\nTo prevent double encoding on the output side MIME::Body->isencoded is set, which tells\nMIME::Body not to encode the data again, if encoded data was requested. This is in\nparticular useful, when it's important that the content must not be modified, e.g. if you\nwant to calculate OpenPGP signatures from it.\n\nWARNING: the semantics change significantly if you parse MIME messages with this option set,\nbecause MIME::Entity resp. MIME::Body *always* see encoded data now, while the default\nbehaviour is working with *decoded* data (and encoding it only if you request it). You need\nto decode the data yourself, if you want to have it decoded.\n\nSo use this option only if you exactly know, what you're doing, and that you're sure, that\nyou really need it.\n" }, { "name": "Parsing an input source", "content": "parsedata DATA\n*Instance method.* Parse a MIME message that's already in core. This internally creates an\n\"in memory\" filehandle on a Perl scalar value using PerlIO\n\nYou may supply the DATA in any of a number of ways...\n\n* A scalar which holds the message. A reference to this scalar will be used internally.\n\n* A ref to a scalar which holds the message. This reference will be used internally.\n\n* DEPRECATED\n\nA ref to an array of scalars. The array is internally concatenated into a temporary\nstring, and a reference to the new string is used internally.\n\nIt is much more efficient to pass in a scalar reference, so please consider refactoring\nyour code to use that interface instead. If you absolutely MUST pass an array, you may\nbe better off using IO::ScalarArray in the calling code to generate a filehandle, and\npassing that filehandle to *parse()*\n\nReturns the parsed MIME::Entity on success.\n\nparse INSTREAM\n*Instance method.* Takes a MIME-stream and splits it into its component entities.\n\nThe INSTREAM can be given as an IO::File, a globref filehandle (like \"\\*STDIN\"), or as *any*\nblessed object conforming to the IO:: interface (which minimally implements getline() and\nread()).\n\nReturns the parsed MIME::Entity on success. Throws exception on failure. If the message\ncontained too many parts (as set by *maxparts*), returns undef.\n\nparseopen EXPR\n*Instance method.* Convenience front-end onto \"parse()\". Simply give this method any\nexpression that may be sent as the second argument to open() to open a filehandle for\nreading.\n\nReturns the parsed MIME::Entity on success. Throws exception on failure.\n\nparsetwo HEADFILE, BODYFILE\n*Instance method.* Convenience front-end onto \"parseopen()\", intended for programs running\nunder mail-handlers like deliver, which splits the incoming mail message into a header file\nand a body file. Simply give this method the paths to the respective files.\n\nWarning: it is assumed that, once the files are cat'ed together, there will be a blank line\nseparating the head part and the body part.\n\nWarning: new implementation slurps files into line array for portability, instead of using\n'cat'. May be an issue if your messages are large.\n\nReturns the parsed MIME::Entity on success. Throws exception on failure.\n" }, { "name": "Specifying output destination", "content": "Warning: in 5.212 and before, this was done by methods of MIME::Parser. However, since many\nusers have requested fine-tuned control over how this is done, the logic has been split off from\nthe parser into its own class, MIME::Parser::Filer Every MIME::Parser maintains an instance of a\nMIME::Parser::Filer subclass to manage disk output (see MIME::Parser::Filer for details.)\n\nThe benefit to this is that the MIME::Parser code won't be confounded with a lot of garbage\nrelated to disk output. The drawback is that the way you override the default behavior will\nchange.\n\nFor now, all the normal public-interface methods are still provided, but many are only stubs\nwhich create or delegate to the underlying MIME::Parser::Filer object.\n\nfiler [FILER]\n*Instance method.* Get/set the FILER object used to manage the output of files to disk. This\nwill be some subclass of MIME::Parser::Filer.\n\noutputdir DIRECTORY\n*Instance method.* Causes messages to be filed directly into the given DIRECTORY. It does\nthis by setting the underlying filer() to a new instance of MIME::Parser::FileInto, and\npassing the arguments into that class' new() method.\n\nNote: Since this method replaces the underlying filer, you must invoke it *before* doing\nchanging any attributes of the filer, like the output prefix; otherwise those changes will\nbe lost.\n\noutputunder BASEDIR, OPTS...\n*Instance method.* Causes messages to be filed directly into subdirectories of the given\nBASEDIR, one subdirectory per message. It does this by setting the underlying filer() to a\nnew instance of MIME::Parser::FileUnder, and passing the arguments into that class' new()\nmethod.\n\nNote: Since this method replaces the underlying filer, you must invoke it *before* doing\nchanging any attributes of the filer, like the output prefix; otherwise those changes will\nbe lost.\n\noutputpath HEAD\n*Instance method, DEPRECATED.* Given a MIME head for a file to be extracted, come up with a\ngood output pathname for the extracted file. Identical to the preferred form:\n\n$parser->filer->outputpath(...args...);\n\nWe just delegate this to the underlying filer() object.\n\noutputprefix [PREFIX]\n*Instance method, DEPRECATED.* Get/set the short string that all filenames for extracted\nbody-parts will begin with (assuming that there is no better \"recommended filename\").\nIdentical to the preferred form:\n\n$parser->filer->outputprefix(...args...);\n\nWe just delegate this to the underlying filer() object.\n\nevilfilename NAME\n*Instance method, DEPRECATED.* Identical to the preferred form:\n\n$parser->filer->evilfilename(...args...);\n\nWe just delegate this to the underlying filer() object.\n\nmaxparts NUM\n*Instance method.* Limits the number of MIME parts we will parse.\n\nNormally, instances of this class parse a message to the bitter end. Messages with many MIME\nparts can cause excessive memory consumption. If you invoke this method, parsing will abort\nwith a die() if a message contains more than NUM parts.\n\nIf NUM is set to -1 (the default), then no maximum limit is enforced.\n\nWith no argument, returns the current setting as an integer\n\noutputtocore YESNO\n*Instance method.* Normally, instances of this class output all their decoded body data to\ndisk files (via MIME::Body::File). However, you can change this behaviour by invoking this\nmethod before parsing:\n\nIf YESNO is false (the default), then all body data goes to disk files.\n\nIf YESNO is true, then all body data goes to in-core data structures This is a little risky\n(what if someone emails you an MPEG or a tar file, hmmm?) but people seem to want this bit\nof noose-shaped rope, so I'm providing it. Note that setting this attribute true *does not*\nmean that parser-internal temporary files are avoided! Use tmptocore() for that.\n\nWith no argument, returns the current setting as a boolean.\n\ntmprecycling\n*Instance method, DEPRECATED.*\n\nThis method is a no-op to preserve the pre-5.421 API.\n\nThe tmprecycling() feature was removed in 5.421 because it had never actually worked.\nPlease update your code to stop using it.\n\ntmptocore [YESNO]\n*Instance method.* Should newtmpfile() create real temp files, or use fake in-core ones?\nNormally we allow the creation of temporary disk files, since this allows us to handle huge\nattachments even when core is limited.\n\nIf YESNO is true, we implement newtmpfile() via in-core handles. If YESNO is false (the\ndefault), we use real tmpfiles. With no argument, just returns the current setting.\n\nuseinnerfiles [YESNO]\n*REMOVED*.\n\n*Instance method.*\n\nMIME::Parser no longer supports IO::InnerFile, but this method is retained for backwards\ncompatibility. It does nothing.\n\nThe original reasoning for IO::InnerFile was that inner files were faster than \"in-core\"\ntemp files. At the time, the \"in-core\" tempfile support was implemented with IO::Scalar from\nthe IO-Stringy distribution, which used the tie() interface to wrap a scalar with the\nappropriate IO::Handle operations. The penalty for this was fairly hefty, and IO::InnerFile\nactually was faster.\n\nNowadays, MIME::Parser uses Perl's built in ability to open a filehandle on an in-memory\nscalar variable via PerlIO. Benchmarking shows that IO::InnerFile is slightly slower than\nusing in-memory temporary files, and is slightly faster than on-disk temporary files. Both\nmeasurements are within a few percent of each other. Since there's no real benefit, and\nsince the IO::InnerFile abuse was fairly hairy and evil (\"writes\" to it were faked by\nextending the size of the inner file with the assumption that the only data you'd ever\n->print() to it would be the line from the \"outer\" file, for example) it's been removed.\n" }, { "name": "Specifying classes to be instantiated", "content": "interface ROLE,[VALUE]\n*Instance method.* During parsing, the parser normally creates instances of certain classes,\nlike MIME::Entity. However, you may want to create a parser subclass that uses your own\nexperimental head, entity, etc. classes (for example, your \"head\" class may provide some\nadditional MIME-field-oriented methods).\n\nIf so, then this is the method that your subclass should invoke during init. Use it like\nthis:\n\npackage MyParser;\n@ISA = qw(MIME::Parser);\n...\nsub init {\nmy $self = shift;\n$self->SUPER::init(@); ### do my parent's init\n$self->interface(ENTITYCLASS => 'MIME::MyEntity');\n$self->interface(HEADCLASS => 'MIME::MyHead');\n$self; ### return\n}\n\nWith no VALUE, returns the VALUE currently associated with that ROLE.\n\nnewbodyfor HEAD\n*Instance method.* Based on the HEAD of a part we are parsing, return a new body object (any\ndesirable subclass of MIME::Body) for receiving that part's data.\n\nIf you set the \"outputtocore\" option to false before parsing (the default), then we call\n\"outputpath()\" and create a new MIME::Body::File on that filename.\n\nIf you set the \"outputtocore\" option to true before parsing, then you get a\nMIME::Body::InCore instead.\n\nIf you want the parser to do something else entirely, you can override this method in a\nsubclass.\n" }, { "name": "Temporary File Creation", "content": "tmpdir DIRECTORY\n*Instance method.* Causes any temporary files created by this parser to be created in the\ngiven DIRECTORY.\n\nIf called without arguments, returns current value.\n\nThe default value is undef, which will cause newtmpfile() to use the system default\ntemporary directory.\n\nnewtmpfile\n*Instance method.* Return an IO handle to be used to hold temporary data during a parse.\n\nThe default uses MIME::Tools::tmpopen() to create a new temporary file, unless tmptocore()\ndictates otherwise, but you can override this. You shouldn't need to.\n\nThe location for temporary files can be changed on a per-parser basis with tmpdir().\n\nIf you do override this, make certain that the object you return is set for binmode(), and\nis able to handle the following methods:\n\nread(BUF, NBYTES)\ngetline()\ngetlines()\nprint(@ARGS)\nflush()\nseek(0, 0)\n\nFatal exception if the stream could not be established.\n" }, { "name": "Parse results and error recovery", "content": "lasterror\n*Instance method.* Return the error (if any) that we ignored in the last parse.\n\nlasthead\n*Instance method.* Return the top-level MIME header of the last stream we attempted to\nparse. This is useful for replying to people who sent us bad MIME messages.\n\n### Parse an input stream:\neval { $entity = $parser->parse(\\*STDIN) };\nif (!$entity) { ### parse failed!\nmy $decapitated = $parser->lasthead;\n...\n}\n\nresults\n*Instance method.* Return an object containing lots of info from the last entity parsed.\nThis will be an instance of class MIME::Parser::Results.\n" } ] }, "OPTIMIZING YOUR PARSER": { "content": "", "subsections": [ { "name": "Maximizing speed", "content": "Optimum input mechanisms:\n\nparse() YES (if you give it a globref or a\nsubclass of IO::File)\nparseopen() YES\nparsedata() NO (see below)\nparsetwo() NO (see below)\n\nOptimum settings:\n\ndecodeheaders() * (no real difference; 0 is slightly faster)\nextractnestedmessages() 0 (may be slightly faster, but in\ngeneral you want it set to 1)\noutputtocore() 0 (will be MUCH faster)\ntmptocore() 0 (will be MUCH faster)\n\nNative I/O is much faster than object-oriented I/O. It's much faster to use <$foo> than\n$foo->getline. For backwards compatibility, this module must continue to use object-oriented I/O\nin most places, but if you use parse() with a \"real\" filehandle (string, globref, or subclass of\nIO::File) then MIME::Parser is able to perform some crucial optimizations.\n\nThe parsetwo() call is very inefficient. Currently this is just a front-end onto parsedata().\nIf your OS supports it, you're *far* better off doing something like:\n\n$parser->parseopen(\"/bin/cat msg.head msg.body |\");\n" }, { "name": "Minimizing memory", "content": "Optimum input mechanisms:\n\nparse() YES\nparseopen() YES\nparsedata() NO (in-core I/O will burn core)\nparsetwo() NO (in-core I/O will burn core)\n\nOptimum settings:\n\ndecodeheaders() * (no real difference)\nextractnestedmessages() * (no real difference)\noutputtocore() 0 (will use MUCH less memory)\ntmptocore is 1)\ntmptocore() 0 (will use MUCH less memory)\n" }, { "name": "Maximizing tolerance of bad MIME", "content": "Optimum input mechanisms:\n\nparse() * (doesn't matter)\nparseopen() * (doesn't matter)\nparsedata() * (doesn't matter)\nparsetwo() * (doesn't matter)\n\nOptimum settings:\n\ndecodeheaders() 0 (sidesteps problem of bad hdr encodings)\nextractnestedmessages() 0 (sidesteps problems of bad nested messages,\nbut often you want it set to 1 anyway).\noutputtocore() * (doesn't matter)\ntmptocore() * (doesn't matter)\n" }, { "name": "Avoiding disk-based temporary files", "content": "Optimum input mechanisms:\n\nparse() YES (if you give it a seekable handle)\nparseopen() YES (becomes a seekable handle)\nparsedata() NO (unless you set tmptocore(1))\nparsetwo() NO (unless you set tmptocore(1))\n\nOptimum settings:\n\ndecodeheaders() * (doesn't matter)\nextractnestedmessages() * (doesn't matter)\noutputtocore() * (doesn't matter)\ntmptocore() 1\n\nYou can veto tmpfiles entirely. You can set tmptocore() true: this will always use in-core I/O\nfor the buffering (warning: this will slow down the parsing of messages with large attachments).\n\nFinal resort. You can always override newtmpfile() in a subclass.\n" } ] }, "WARNINGS": { "content": "Multipart messages are always read line-by-line\nMultipart document parts are read line-by-line, so that the encapsulation boundaries may\neasily be detected. However, bad MIME composition agents (for example, naive CGI scripts)\nmight return multipart documents where the parts are, say, unencoded bitmap files... and,\nconsequently, where such \"lines\" might be veeeeeeeeery long indeed.\n\nA better solution for this case would be to set up some form of state machine for input\nprocessing. This will be left for future versions.\n\nMultipart parts read into temp files before decoding\nIn my original implementation, the MIME::Decoder classes had to be aware of encapsulation\nboundaries in multipart MIME documents. While this decode-while-parsing approach obviated\nthe need for temporary files, it resulted in inflexible and complex decoder implementations.\n\nThe revised implementation uses a temporary file (a la \"tmpfile()\") during parsing to hold\nthe *encoded* portion of the current MIME document or part. This file is deleted\nautomatically after the current part is decoded and the data is written to the \"body stream\"\nobject; you'll never see it, and should never need to worry about it.\n\nSome folks have asked for the ability to bypass this temp-file mechanism, I suppose because\nthey assume it would slow down their application. I considered accommodating this wish, but\nthe temp-file approach solves a lot of thorny problems in parsing, and it also protects\nagainst hidden bugs in user applications (what if you've directed the encoded part into a\nscalar, and someone unexpectedly sends you a 6 MB tar file?). Finally, I'm just not\nconvinced that the temp-file use adds significant overhead.\n\nFuzzing of CRLF and newline on input\nRFC 2045 dictates that MIME streams have lines terminated by CRLF (\"\\r\\n\"). However, it is\nextremely likely that folks will want to parse MIME streams where each line ends in the\nlocal newline character \"\\n\" instead.\n\nAn attempt has been made to allow the parser to handle both CRLF and newline-terminated\ninput.\n\nFuzzing of CRLF and newline on output\nThe \"7bit\" and \"8bit\" decoders will decode both a \"\\n\" and a \"\\r\\n\" end-of-line sequence\ninto a \"\\n\".\n\nThe \"binary\" decoder (default if no encoding specified) still outputs stuff verbatim... so a\nMIME message with CRLFs and no explicit encoding will be output as a text file that, on many\nsystems, will have an annoying ^M at the end of each line... *but this is as it should be*.\n\nInability to handle multipart boundaries that contain newlines\nFirst, let's get something straight: *this is an evil, EVIL practice,* and is incompatible\nwith RFC 2046... hence, it's not valid MIME.\n\nIf your mailer creates multipart boundary strings that contain newlines *when they appear in\nthe message body,* give it two weeks notice and find another one. If your mail robot\nreceives MIME mail like this, regard it as syntactically incorrect MIME, which it is.\n\nWhy do I say that? Well, in RFC 2046, the syntax of a boundary is given quite clearly:\n\nboundary := 0*69 bcharsnospace\n\nbchars := bcharsnospace / \" \"\n\nbcharsnospace := DIGIT / ALPHA / \"'\" / \"(\" / \")\" / \"+\" /\"\"\n/ \",\" / \"-\" / \".\" / \"/\" / \":\" / \"=\" / \"?\"\n\nAll of which means that a valid boundary string *cannot* have newlines in it, and any\nnewlines in such a string in the message header are expected to be solely the result of\n*folding* the string (i.e., inserting to-be-removed newlines for readability and\nline-shortening *only*).\n\nYet, there is at least one brain-damaged user agent out there that composes mail like this:\n\nMIME-Version: 1.0\nContent-type: multipart/mixed; boundary=\"----ABC-\n123----\"\nSubject: Hi... I'm a dork!\n\nThis is a multipart MIME message (yeah, right...)\n\n----ABC-\n123----\n\nHi there!\n\nWe have *got* to discourage practices like this (and the recent file upload idiocy where\nbinary files that are part of a multipart MIME message aren't base64-encoded) if we want\nMIME to stay relatively simple, and MIME parsers to be relatively robust.\n\n*Thanks to Andreas Koenig for bringing a baaaaaaaaad user agent to my attention.*\n", "subsections": [] }, "SEE ALSO": { "content": "MIME::Tools, MIME::Head, MIME::Body, MIME::Entity, MIME::Decoder\n", "subsections": [] }, "AUTHOR": { "content": "Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com). Dianne Skoll\n(dfs@roaringpenguin.com) http://www.roaringpenguin.com\n\nAll rights reserved. This program is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.\n", "subsections": [] } } } }