{
    "content": [
        {
            "type": "text",
            "text": "# MIME::Decoder (perldoc)\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 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\nThis abstract class, and its private concrete subclasses (see below) provide an OO front end to\nthe actions of...\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS** (3 subsections)\n- **DESCRIPTION**\n- **PUBLIC INTERFACE** (2 subsections)\n- **DECODER SUBCLASSES**\n- **NOTES** (1 subsections)\n- **SEE ALSO**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "MIME::Decoder",
        "section": "",
        "mode": "perldoc",
        "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 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": "Decoding a data stream",
                        "lines": 8
                    },
                    {
                        "name": "Encoding a data stream",
                        "lines": 8
                    },
                    {
                        "name": "Non-standard encodings",
                        "lines": 12
                    }
                ]
            },
            {
                "name": "DESCRIPTION",
                "lines": 12,
                "subsections": []
            },
            {
                "name": "PUBLIC INTERFACE",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Standard interface",
                        "lines": 67
                    },
                    {
                        "name": "Subclass interface",
                        "lines": 68
                    }
                ]
            },
            {
                "name": "DECODER SUBCLASSES",
                "lines": 17,
                "subsections": []
            },
            {
                "name": "NOTES",
                "lines": 14,
                "subsections": [
                    {
                        "name": "Writing a decoder",
                        "lines": 58
                    }
                ]
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 7,
                "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 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": "Decoding a data stream",
                        "content": "Here's a simple filter program to read quoted-printable data from STDIN (until EOF) and write\nthe 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"
                    },
                    {
                        "name": "Encoding a data stream",
                        "content": "Here's a simple filter program to read binary data from STDIN (until EOF) and write\nbase64-encoded data to STDOUT:\n\nuse MIME::Decoder;\n\n$decoder = new MIME::Decoder 'base64' or die \"unsupported\";\n$decoder->encode(\\*STDIN, \\*STDOUT);\n"
                    },
                    {
                        "name": "Non-standard encodings",
                        "content": "You can write and install your own decoders so that MIME::Decoder will know 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"
                    }
                ]
            },
            "DESCRIPTION": {
                "content": "This abstract class, and its private concrete subclasses (see below) provide an OO front end to\nthe actions of...\n\n*   Decoding a MIME-encoded stream\n\n*   Encoding a raw data stream into a MIME-encoded stream.\n\nThe constructor for MIME::Decoder takes the name of an encoding (\"base64\", \"7bit\", etc.), and\nreturns an instance of a *subclass* of MIME::Decoder whose \"decode()\" method will perform the\nappropriate decoding action, and whose \"encode()\" method will perform the appropriate encoding\naction.\n",
                "subsections": []
            },
            "PUBLIC INTERFACE": {
                "content": "",
                "subsections": [
                    {
                        "name": "Standard interface",
                        "content": "If all you are doing is *using* this class, here's all you'll need...\n\nnew ENCODING\n*Class method, constructor.* Create and return a new decoder object which can handle the\ngiven ENCODING.\n\nmy $decoder = new MIME::Decoder \"7bit\";\n\nReturns the undefined value if no known decoders are appropriate.\n\nbest ENCODING\n*Class method, constructor.* Exactly like new(), except that this defaults any unsupported\nencoding to \"binary\", after raising a suitable warning (it's a fatal error if there's no\nbinary 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\n*Instance method.* Decode the document waiting in the input handle INSTREAM, writing the\ndecoded information to the output handle OUTSTREAM.\n\nRead the section in this document on I/O handles for more information about the arguments.\nNote that you can still supply old-style unblessed filehandles for INSTREAM and OUTSTREAM.\n\nReturns true on success, throws exception on failure.\n\nencode INSTREAM,OUTSTREAM\n*Instance method.* Encode the document waiting in the input filehandle INSTREAM, writing the\nencoded information to the output stream OUTSTREAM.\n\nRead the section in this document on I/O handles for more information about the arguments.\nNote that you can still supply old-style unblessed filehandles for INSTREAM and OUTSTREAM.\n\nReturns true on success, throws exception on failure.\n\nencoding\n*Instance method.* Return the encoding that this object was created to handle, coerced to\nall lowercase (e.g., \"base64\").\n\nhead [HEAD]\n*Instance method.* Completely optional: some decoders need to know a little about the file\nthey are encoding/decoding; e.g., x-uu likes to have the filename. The HEAD is any object\nwhich responds to messages like:\n\n$head->mimeattr('content-disposition.filename');\n\nsupported [ENCODING]\n*Class method.* With one arg (an ENCODING name), returns truth if that encoding is currently\nhandled, and falsity otherwise. The ENCODING 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 decoders, where the key is the\nencoding name (all lowercase, like '7bit'), and the value is true (it happens to be the name\nof the class that handles the decoding, but you probably shouldn't rely on that). You may\nsafely modify this hash; it will *not* change the way the module performs its lookups. Only\n\"install\" can do that.\n\n*Thanks to Achim Bohnet for suggesting this method.*\n"
                    },
                    {
                        "name": "Subclass interface",
                        "content": "If you are writing (or installing) a new decoder subclass, there are some other methods you'll\nneed to know about:\n\ndecodeit INSTREAM,OUTSTREAM\n*Abstract instance method.* The back-end of the decode method. It takes an input handle\nopened for reading (INSTREAM), and an output handle opened for writing (OUTSTREAM).\n\nIf you are writing your own decoder subclass, you must override this method in your class.\nYour method should read from the input handle via \"getline()\" or \"read()\", decode this\ninput, and print the decoded data to the output handle via \"print()\". You may do this\nhowever you see fit, so long as the end result is the same.\n\nNote that unblessed references and globrefs are automatically turned into I/O handles for\nyou by \"decode()\", so you don't need to worry about it.\n\nYour method must return either \"undef\" (to indicate failure), or 1 (to indicate success). It\nmay also throw an exception to indicate failure.\n\nencodeit INSTREAM,OUTSTREAM\n*Abstract instance method.* The back-end of the encode method. It takes an input handle\nopened for reading (INSTREAM), and an output handle opened for writing (OUTSTREAM).\n\nIf you are writing your own decoder subclass, you must override this method in your class.\nYour method should read from the input handle via \"getline()\" or \"read()\", encode this\ninput, and print the encoded data to the output handle via \"print()\". You may do this\nhowever you see fit, so long as the end result is the same.\n\nNote that unblessed references and globrefs are automatically turned into I/O handles for\nyou by \"encode()\", so you don't need to worry about it.\n\nYour method must return either \"undef\" (to indicate failure), or 1 (to indicate success). It\nmay also throw an exception to indicate failure.\n\nfilter IN, OUT, COMMAND...\n*Class method, utility.* If your decoder involves an external program, you can invoke them\neasily through this method. The command must be a \"filter\": a command that reads input from\nits STDIN (which will come from the IN argument) and writes output to its STDOUT (which will\ngo 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 internally), so you can specify\nCOMMAND as a single argument or as an array.\n\ninit ARGS...\n*Instance method.* Do any necessary initialization of the new instance, taking whatever\narguments were given to \"new()\". Should return the self object on success, undef on failure.\n\ninstall ENCODINGS...\n*Class method*. Install this class so that each encoding in ENCODINGS is handled by it:\n\ninstall MyBase64Decoder 'base64', 'x-base64super';\n\nYou should not override this method.\n\nuninstall ENCODINGS...\n*Class method*. Uninstall support for encodings. This is a way to turn off the decoding of\n\"experimental\" encodings. For safety, always use MIME::Decoder directly:\n\nuninstall MIME::Decoder 'x-uu', 'x-uuencode';\n\nYou should not override this method.\n"
                    }
                ]
            },
            "DECODER SUBCLASSES": {
                "content": "You don't need to \"use\" any other Perl modules; the following \"standard\" subclasses are included\nas part of MIME::Decoder:\n\nClass:                         Handles encodings:\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\nClass:                         Handles encodings:\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 MIME::Body class... which means\nthat input and output routines cannot just assume that they are dealing with filehandles.\n\nTherefore, all that MIME::Decoder and its subclasses require (and, thus, all that they can\nassume) is that INSTREAMs and OUTSTREAMs are objects which respond to a subset of the messages\ndefined in the IO::Handle interface; minimally:\n\nprint\ngetline\nread(BUF,NBYTES)\n\n*Thanks to Achim Bohnet for suggesting this more-generic I/O model.*\n",
                "subsections": [
                    {
                        "name": "Writing a decoder",
                        "content": "If you're experimenting with your own encodings, you'll probably want to write a decoder. Here\nare the basics:\n\n1.  Create a module, like \"MyDecoder::\", for your decoder. Declare it to be a subclass of\nMIME::Decoder.\n\n2.  Create the following instance methods in your class, as described above:\n\ndecodeit\nencodeit\ninit\n\n3.  In your application program, activate your decoder for one or more encodings 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\" encoding:\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\" encoding can easily be\nconverted line-by-line... as can even \"7bit\" and \"8bit\" (since all these encodings guarantee\nshort lines, with a max of 1000 characters). The good news is: it is very likely that it will be\nsimilarly-easy to write a MIME::Decoder for any future standard encodings.\n\nThe \"binary\" decoder, however, really required block reads and writes: see\n\"MIME::Decoder::Binary\" for details.\n"
                    }
                ]
            },
            "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 redistribute it and/or modify it\nunder the same terms as Perl itself.\n\n1;\n",
                "subsections": []
            }
        }
    }
}