{ "content": [ { "type": "text", "text": "# MIME::Decoder (info)\n\n## NAME\n\nMIME::Decoder - an object for decoding the body part of a MIME stream\n\n## SYNOPSIS\n\nBefore reading further, you should see MIME::Tools to make sure that\nyou understand where this module fits into the grand scheme of things.\nGo on, do it now. I'll wait.\nReady? Ok...\nDecoding a data stream\nHere's a simple filter program to read quoted-printable data from STDIN\n(until EOF) and write the decoded data to STDOUT:\nuse MIME::Decoder;\n$decoder = new MIME::Decoder 'quoted-printable' or die \"unsupported\";\n$decoder->decode(\\*STDIN, \\*STDOUT);\nEncoding a data stream\nHere's a simple filter program to read binary data from STDIN (until\nEOF) and write base64-encoded data to STDOUT:\nuse MIME::Decoder;\n$decoder = new MIME::Decoder 'base64' or die \"unsupported\";\n$decoder->encode(\\*STDIN, \\*STDOUT);\nNon-standard encodings\nYou can write and install your own decoders so that MIME::Decoder will\nknow about them:\nuse MyBase64Decoder;\ninstall MyBase64Decoder 'base64';\nYou can also test if a given encoding is supported:\nif (supported MIME::Decoder 'x-uuencode') {\n### we can uuencode!\n}\n\n## DESCRIPTION\n\nThis abstract class, and its private concrete subclasses (see below)\nprovide an OO front end to the actions of...\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **PUBLIC INTERFACE**\n- **DECODER SUBCLASSES**\n- **NOTES**\n- **SEE ALSO**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "MIME::Decoder", "section": "", "mode": "info", "summary": "MIME::Decoder - an object for decoding the body part of a MIME stream", "synopsis": "Before reading further, you should see MIME::Tools to make sure that\nyou understand where this module fits into the grand scheme of things.\nGo on, do it now. I'll wait.\nReady? Ok...\nDecoding a data stream\nHere's a simple filter program to read quoted-printable data from STDIN\n(until EOF) and write the decoded data to STDOUT:\nuse MIME::Decoder;\n$decoder = new MIME::Decoder 'quoted-printable' or die \"unsupported\";\n$decoder->decode(\\*STDIN, \\*STDOUT);\nEncoding a data stream\nHere's a simple filter program to read binary data from STDIN (until\nEOF) and write base64-encoded data to STDOUT:\nuse MIME::Decoder;\n$decoder = new MIME::Decoder 'base64' or die \"unsupported\";\n$decoder->encode(\\*STDIN, \\*STDOUT);\nNon-standard encodings\nYou can write and install your own decoders so that MIME::Decoder will\nknow about them:\nuse MyBase64Decoder;\ninstall MyBase64Decoder 'base64';\nYou can also test if a given encoding is supported:\nif (supported MIME::Decoder 'x-uuencode') {\n### we can uuencode!\n}", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 38, "subsections": [] }, { "name": "DESCRIPTION", "lines": 13, "subsections": [] }, { "name": "PUBLIC INTERFACE", "lines": 157, "subsections": [] }, { "name": "DECODER SUBCLASSES", "lines": 13, "subsections": [] }, { "name": "NOTES", "lines": 80, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "AUTHOR", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "MIME::Decoder - an object for decoding the body part of a MIME stream\n", "subsections": [] }, "SYNOPSIS": { "content": "Before reading further, you should see MIME::Tools to make sure that\nyou understand where this module fits into the grand scheme of things.\nGo on, do it now. I'll wait.\n\nReady? Ok...\n\nDecoding a data stream\nHere's a simple filter program to read quoted-printable data from STDIN\n(until EOF) and write the decoded data to STDOUT:\n\nuse MIME::Decoder;\n\n$decoder = new MIME::Decoder 'quoted-printable' or die \"unsupported\";\n$decoder->decode(\\*STDIN, \\*STDOUT);\n\nEncoding a data stream\nHere's a simple filter program to read binary data from STDIN (until\nEOF) and write base64-encoded data to STDOUT:\n\nuse MIME::Decoder;\n\n$decoder = new MIME::Decoder 'base64' or die \"unsupported\";\n$decoder->encode(\\*STDIN, \\*STDOUT);\n\nNon-standard encodings\nYou can write and install your own decoders so that MIME::Decoder will\nknow about them:\n\nuse MyBase64Decoder;\n\ninstall MyBase64Decoder 'base64';\n\nYou can also test if a given encoding is supported:\n\nif (supported MIME::Decoder 'x-uuencode') {\n### we can uuencode!\n}\n", "subsections": [] }, "DESCRIPTION": { "content": "This abstract class, and its private concrete subclasses (see below)\nprovide an OO front end to the actions of...\n\no Decoding a MIME-encoded stream\n\no Encoding a raw data stream into a MIME-encoded stream.\n\nThe constructor for MIME::Decoder takes the name of an encoding\n(\"base64\", \"7bit\", etc.), and returns an instance of a subclass of\nMIME::Decoder whose \"decode()\" method will perform the appropriate\ndecoding action, and whose \"encode()\" method will perform the\nappropriate encoding action.\n", "subsections": [] }, "PUBLIC INTERFACE": { "content": "Standard interface\nIf all you are doing is using this class, here's all you'll need...\n\nnew ENCODING\nClass method, constructor. Create and return a new decoder object\nwhich can handle the given ENCODING.\n\nmy $decoder = new MIME::Decoder \"7bit\";\n\nReturns the undefined value if no known decoders are appropriate.\n\nbest ENCODING\nClass method, constructor. Exactly like new(), except that this\ndefaults any unsupported encoding to \"binary\", after raising a\nsuitable warning (it's a fatal error if there's no binary decoder).\n\nmy $decoder = best MIME::Decoder \"x-gzip64\";\n\nWill either return a decoder, or a raise a fatal exception.\n\ndecode INSTREAM,OUTSTREAM\nInstance method. Decode the document waiting in the input handle\nINSTREAM, writing the decoded information to the output handle\nOUTSTREAM.\n\nRead the section in this document on I/O handles for more\ninformation about the arguments. Note that you can still supply\nold-style unblessed filehandles for INSTREAM and OUTSTREAM.\n\nReturns true on success, throws exception on failure.\n\nencode INSTREAM,OUTSTREAM\nInstance method. Encode the document waiting in the input\nfilehandle INSTREAM, writing the encoded information to the output\nstream OUTSTREAM.\n\nRead the section in this document on I/O handles for more\ninformation about the arguments. Note that you can still supply\nold-style unblessed filehandles for INSTREAM and OUTSTREAM.\n\nReturns true on success, throws exception on failure.\n\nencoding\nInstance method. Return the encoding that this object was created\nto handle, coerced to all lowercase (e.g., \"base64\").\n\nhead [HEAD]\nInstance method. Completely optional: some decoders need to know a\nlittle about the file they are encoding/decoding; e.g., x-uu likes\nto have the filename. The HEAD is any object which responds to\nmessages like:\n\n$head->mimeattr('content-disposition.filename');\n\nsupported [ENCODING]\nClass method. With one arg (an ENCODING name), returns truth if\nthat encoding is currently handled, and falsity otherwise. The\nENCODING will be automatically coerced to lowercase:\n\nif (supported MIME::Decoder '7BIT') {\n### yes, we can handle it...\n}\nelse {\n### drop back six and punt...\n}\n\nWith no args, returns a reference to a hash of all available\ndecoders, where the key is the encoding name (all lowercase, like\n'7bit'), and the value is true (it happens to be the name of the\nclass that handles the decoding, but you probably shouldn't rely on\nthat). You may safely modify this hash; it will not change the way\nthe module performs its lookups. Only \"install\" can do that.\n\nThanks to Achim Bohnet for suggesting this method.\n\nSubclass interface\nIf you are writing (or installing) a new decoder subclass, there are\nsome other methods you'll need to know about:\n\ndecodeit INSTREAM,OUTSTREAM\nAbstract instance method. The back-end of the decode method. It\ntakes an input handle opened for reading (INSTREAM), and an output\nhandle opened for writing (OUTSTREAM).\n\nIf you are writing your own decoder subclass, you must override\nthis method in your class. Your method should read from the input\nhandle via \"getline()\" or \"read()\", decode this input, and print\nthe decoded data to the output handle via \"print()\". You may do\nthis however you see fit, so long as the end result is the same.\n\nNote that unblessed references and globrefs are automatically\nturned into I/O handles for you by \"decode()\", so you don't need to\nworry about it.\n\nYour method must return either \"undef\" (to indicate failure), or 1\n(to indicate success). It may also throw an exception to indicate\nfailure.\n\nencodeit INSTREAM,OUTSTREAM\nAbstract instance method. The back-end of the encode method. It\ntakes an input handle opened for reading (INSTREAM), and an output\nhandle opened for writing (OUTSTREAM).\n\nIf you are writing your own decoder subclass, you must override\nthis method in your class. Your method should read from the input\nhandle via \"getline()\" or \"read()\", encode this input, and print\nthe encoded data to the output handle via \"print()\". You may do\nthis however you see fit, so long as the end result is the same.\n\nNote that unblessed references and globrefs are automatically\nturned into I/O handles for you by \"encode()\", so you don't need to\nworry about it.\n\nYour method must return either \"undef\" (to indicate failure), or 1\n(to indicate success). It may also throw an exception to indicate\nfailure.\n\nfilter IN, OUT, COMMAND...\nClass method, utility. If your decoder involves an external\nprogram, you can invoke them easily through this method. The\ncommand must be a \"filter\": a command that reads input from its\nSTDIN (which will come from the IN argument) and writes output to\nits STDOUT (which will go to the OUT argument).\n\nFor example, here's a decoder that un-gzips its data:\n\nsub decodeit {\nmy ($self, $in, $out) = @;\n$self->filter($in, $out, \"gzip -d -\");\n}\n\nThe usage is similar to IPC::Open2::open2 (which it uses\ninternally), so you can specify COMMAND as a single argument or as\nan array.\n\ninit ARGS...\nInstance method. Do any necessary initialization of the new\ninstance, taking whatever arguments were given to \"new()\". Should\nreturn the self object on success, undef on failure.\n\ninstall ENCODINGS...\nClass method. Install this class so that each encoding in\nENCODINGS is handled by it:\n\ninstall MyBase64Decoder 'base64', 'x-base64super';\n\nYou should not override this method.\n\nuninstall ENCODINGS...\nClass method. Uninstall support for encodings. This is a way to\nturn off the decoding of \"experimental\" encodings. For safety,\nalways use MIME::Decoder directly:\n\nuninstall MIME::Decoder 'x-uu', 'x-uuencode';\n\nYou should not override this method.\n", "subsections": [] }, "DECODER SUBCLASSES": { "content": "You don't need to \"use\" any other Perl modules; the following\n\"standard\" subclasses are included as part of MIME::Decoder:\n\nMIME::Decoder::Binary binary\nMIME::Decoder::NBit 7bit, 8bit\nMIME::Decoder::Base64 base64\nMIME::Decoder::QuotedPrint quoted-printable\n\nThe following \"non-standard\" subclasses are also included:\n\nMIME::Decoder::UU x-uu, x-uuencode\nMIME::Decoder::Gzip64 x-gzip64 requires gzip!\n", "subsections": [] }, "NOTES": { "content": "Input/Output handles\nAs of MIME-tools 2.0, this class has to play nice with the new\nMIME::Body class... which means that input and output routines cannot\njust assume that they are dealing with filehandles.\n\nTherefore, all that MIME::Decoder and its subclasses require (and,\nthus, all that they can assume) is that INSTREAMs and OUTSTREAMs are\nobjects which respond to a subset of the messages defined in the\nIO::Handle interface; minimally:\n\nprint\ngetline\nread(BUF,NBYTES)\n\nThanks to Achim Bohnet for suggesting this more-generic I/O model.\n\nWriting a decoder\nIf you're experimenting with your own encodings, you'll probably want\nto write a decoder. Here are the basics:\n\n1. Create a module, like \"MyDecoder::\", for your decoder. Declare it\nto be a subclass of MIME::Decoder.\n\n2. Create the following instance methods in your class, as described\nabove:\n\ndecodeit\nencodeit\ninit\n\n3. In your application program, activate your decoder for one or more\nencodings like this:\n\nrequire MyDecoder;\n\ninstall MyDecoder \"7bit\"; ### use MyDecoder to decode \"7bit\"\ninstall MyDecoder \"x-foo\"; ### also use MyDecoder to decode \"x-foo\"\n\nTo illustrate, here's a custom decoder class for the \"quoted-printable\"\nencoding:\n\npackage MyQPDecoder;\n\n@ISA = qw(MIME::Decoder);\nuse MIME::Decoder;\nuse MIME::QuotedPrint;\n\n### decodeit - the private decoding method\nsub decodeit {\nmy ($self, $in, $out) = @;\nlocal $;\nwhile (defined($ = $in->getline)) {\nmy $decoded = decodeqp($);\n$out->print($decoded);\n}\n1;\n}\n\n### encodeit - the private encoding method\nsub encodeit {\nmy ($self, $in, $out) = @;\n\nmy ($buf, $nread) = ('', 0);\nwhile ($in->read($buf, 60)) {\nmy $encoded = encodeqp($buf);\n$out->print($encoded);\n}\n1;\n}\n\nThat's it. The task was pretty simple because the \"quoted-printable\"\nencoding can easily be converted line-by-line... as can even \"7bit\" and\n\"8bit\" (since all these encodings guarantee short lines, with a max of\n1000 characters). The good news is: it is very likely that it will be\nsimilarly-easy to write a MIME::Decoder for any future standard\nencodings.\n\nThe \"binary\" decoder, however, really required block reads and writes:\nsee \"MIME::Decoder::Binary\" for details.\n", "subsections": [] }, "SEE ALSO": { "content": "MIME::Tools, other MIME::Decoder subclasses.\n", "subsections": [] }, "AUTHOR": { "content": "Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).\n\nAll rights reserved. This program is free software; you can\nredistribute it and/or modify it under the same terms as Perl itself.\n\n1;\n\nperl v5.26.1 2017-10-20 MIME::Decoder(3pm)", "subsections": [] } } } }