This module is BETA code, which means that the interfaces are fairly stable BUT it has not been out in the community long enough to guarantee much testing. Use with caution! Please report any errors back to eryq@zeegee.com as soon as you can.
MIME::Decoder - an object for decoding the body part of a MIME stream
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...
Here's a simple filter program to read quoted-printable data from STDIN
(until EOF) and write the decoded data to STDOUT:
use MIME::Decoder;
$decoder = new MIME::Decoder 'quoted-printable' or die "unsupported";
$decoder->decode(\*STDIN, \*STDOUT);
Here's a simple filter program to read binary data from STDIN
(until EOF) and write base64-encoded data to STDOUT:
use MIME::Decoder;
$decoder = new MIME::Decoder 'base64' or die "unsupported";
$decoder->encode(\*STDIN, \*STDOUT);
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!
}
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.
If all you are doing is using this class, here's all you'll need...
my $decoder = new MIME::Decoder "7bit";
Returns the undefined value if no known decoders are appropriate.
my $decoder = best MIME::Decoder "x-gzip64";
Will either return a decoder, or a raise a fatal exception.
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.
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.
"base64"
).
$head->mime_attr('content-disposition.filename');
if (supported MIME::Decoder '7BIT') { ### yes, we can handle it... } else { ### drop back six and punt... }
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.
If you are writing (or installing) a new decoder subclass, there are some other methods you'll need to know about:
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.
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.
For example, here's a decoder that un-gzips its data:
sub decode_it {
my ($self, $in, $out) = @_;
$self->filter($in, $out, "gzip -d -");
}
The usage is similar to IPC::Open2::open2 (which it uses internally), so you can specify COMMAND as a single argument or as an array.
new()
.
Should return the self object on success, undef on failure.
install MyBase64Decoder 'base64', 'x-base64super';
You should not override this method.
uninstall MIME::Decoder 'x-uu', 'x-uuencode';
You should not override this method.
You don't need to "use"
any other Perl modules; the
following "standard" subclasses are included as part of MIME::Decoder:
Class: Handles encodings: |
---|
MIME::Decoder::Binary binary |
MIME::Decoder::NBit 7bit, 8bit |
MIME::Decoder::Base64 base64 |
MIME::Decoder::QuotedPrint quoted-printable |
The following "non-standard" subclasses are also included:
Class: Handles encodings: |
---|
MIME::Decoder::UU x-uu, x-uuencode |
MIME::Decoder::Gzip64 x-gzip64 ** requires gzip! |
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)
For backwards compatibilty, if you supply a scalar filehandle name
(like "STDOUT"
) or an unblessed glob reference (like \*STDOUT
)
where an INSTREAM or OUTSTREAM is expected, this package will
automatically wrap it in an object that fits these criteria, via IO::Wrap.
Thanks to Achim Bohnet for suggesting this more-generic I/O model.
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:
require MyDecoder;
install MyDecoder "7bit"; ### use MyDecoder to decode "7bit"
install MyDecoder "x-foo"; ### also use MyDecoder to decode "x-foo"
To illustrate, here's a custom decoder class for the quoted-printable
encoding:
package MyQPDecoder;
@ISA = qw(MIME::Decoder);
use MIME::Decoder;
use MIME::QuotedPrint;
### decode_it - the private decoding method
sub decode_it {
my ($self, $in, $out) = @_;
while (defined($_ = $in->getline)) {
my $decoded = decode_qp($_);
$out->print($decoded);
}
1;
}
### encode_it - the private encoding method
sub encode_it {
my ($self, $in, $out) = @_;
my ($buf, $nread) = ('', 0);
while ($in->read($buf, 60)) {
my $encoded = encode_qp($buf);
$out->print($encoded);
}
1;
}
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.
The "binary"
decoder, however, really required block reads and writes:
see MIME::Decoder::Binary for details.
Eryq (
All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
$Revision: 1.1 $ $Date: 2004/04/09 17:04:45 $