Non-standard encodings

You can write and install your own decoders so that MIME::Decoder will know about them:

use MyBase64Decoder;
install MyBase64Decoder 'base64';

You can also test if a given encoding is supported:

if (supported MIME::Decoder 'x-uuencode') {
### we can uuencode!
}

DESCRIPTION

This abstract class, and its private concrete subclasses (see below) provide an OO front end to the actions of...

Decoding a MIME-encoded stream

Encoding a raw data stream into a MIME-encoded stream.

The constructor for MIME::Decoder takes the name of an encoding (base64, 7bit, etc.), and returns an instance of a subclass of MIME::Decoder whose decode() method will perform the appropriate decoding action, and whose encode() method will perform the appropriate encoding action.

PUBLIC INTERFACE

Standard interface

If all you are doing is using this class, here's all you'll need...

new ENCODING

Class method, constructor. Create and return a new decoder object which can handle the given ENCODING.

my $decoder = new MIME::Decoder "7bit";

Returns the undefined value if no known decoders are appropriate.

best ENCODING

Class method, constructor. Exactly like new(), except that this defaults any unsupported encoding to "binary", after raising a suitable warning (it's a fatal error if there's no binary decoder).

my $decoder = best MIME::Decoder "x-gzip64";

Will either return a decoder, or a raise a fatal exception.

decode INSTREAM,OUTSTREAM

Instance method. Decode the document waiting in the input handle INSTREAM, writing the decoded information to the output handle OUTSTREAM.

Read the section in this document on I/O handles for more information about the arguments. Note that you can still supply old-style unblessed filehandles for INSTREAM and OUTSTREAM.

Returns true on success, throws exception on failure.

encode INSTREAM,OUTSTREAM

Instance method. Encode the document waiting in the input filehandle INSTREAM, writing the encoded information to the output stream OUTSTREAM.

Read the section in this document on I/O handles for more information about the arguments. Note that you can still supply old-style unblessed filehandles for INSTREAM and OUTSTREAM.

Returns true on success, throws exception on failure.

encoding

Instance method. Return the encoding that this object was created to handle, coerced to all lowercase (e.g., "base64").

head [HEAD]

Instance method. Completely optional: some decoders need to know a little about the file they are encoding/decoding; e.g., x-uu likes to have the filename. The HEAD is any object which responds to messages like:

$head->mime_attr('content-disposition.filename');

supported [ENCODING]

Class method. With one arg (an ENCODING name), returns truth if that encoding is currently handled, and falsity otherwise. The ENCODING will be automatically coerced to lowercase:

With no args, returns a reference to a hash of all available decoders, where the key is the encoding name (all lowercase, like '7bit'), and the value is true (it happens to be the name of the class that handles the decoding, but you probably shouldn't rely on that). You may safely modify this hash; it will not change the way the module performs its lookups. Only install can do that.

Thanks to Achim Bohnet for suggesting this method.

Subclass interface

If you are writing (or installing) a new decoder subclass, there are some other methods you'll need to know about:

decode_it INSTREAM,OUTSTREAM

Abstract instance method. The back-end of the decode method. It takes an input handle opened for reading (INSTREAM), and an output handle opened for writing (OUTSTREAM).

If you are writing your own decoder subclass, you must override this method in your class. Your method should read from the input handle via getline() or read(), decode this input, and print the decoded data to the output handle via print(). You may do this however you see fit, so long as the end result is the same.

Note that unblessed references and globrefs are automatically turned into I/O handles for you by decode(), so you don't need to worry about it.

Your method must return either undef (to indicate failure), or 1 (to indicate success). It may also throw an exception to indicate failure.

encode_it INSTREAM,OUTSTREAM

Abstract instance method. The back-end of the encode method. It takes an input handle opened for reading (INSTREAM), and an output handle opened for writing (OUTSTREAM).

If you are writing your own decoder subclass, you must override this method in your class. Your method should read from the input handle via getline() or read(), encode this input, and print the encoded data to the output handle via print(). You may do this however you see fit, so long as the end result is the same.

Note that unblessed references and globrefs are automatically turned into I/O handles for you by encode(), so you don't need to worry about it.

Your method must return either undef (to indicate failure), or 1 (to indicate success). It may also throw an exception to indicate failure.

filter IN, OUT, COMMAND...

Class method, utility. If your decoder involves an external program, you can invoke them easily through this method. The command must be a "filter": a command that reads input from its STDIN (which will come from the IN argument) and writes output to its STDOUT (which will go to the OUT argument).

NOTES

Input/Output handles

As of MIME-tools 2.0, this class has to play nice with the new MIME::Body class... which means that input and output routines cannot just assume that they are dealing with filehandles.

Therefore, all that MIME::Decoder and its subclasses require (and, thus, all that they can assume) is that INSTREAMs and OUTSTREAMs are objects which respond to a subset of the messages defined in the IO::Handle interface; minimally:

print
getline
read(BUF,NBYTES)

Thanks to Achim Bohnet for suggesting this more-generic I/O model.

Writing a decoder

If you're experimenting with your own encodings, you'll probably want to write a decoder. Here are the basics:

Create a module, like "MyDecoder::", for your decoder. Declare it to be a subclass of MIME::Decoder.

Create the following instance methods in your class, as described above:

decode_it
encode_it
init

In your application program, activate your decoder for one or more encodings like this:

That's it. The task was pretty simple because the "quoted-printable" encoding can easily be converted line-by-line... as can even "7bit" and "8bit" (since all these encodings guarantee short lines, with a max of 1000 characters). The good news is: it is very likely that it will be similarly-easy to write a MIME::Decoder for any future standard encodings.