WARNING: This code is in an evaluation phase until 1 August 1996. Depending on any comments/complaints received before this cutoff date, the interface may change in a non-backwards-compatible manner.
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.
You can even create your own subclasses and ``install'' them so that
MIME::Decoder will know about them, via the install()
method
Want to know if a given encoding is currently supported? Use the supported()
class method.
#!/usr/bin/perl use MIME::Decoder;
$encoding = 'quoted-printable'; $decoder = new MIME::Decoder $encoding or die "$encoding unsupported"; $decoder->decode(\*STDIN, \*STDOUT);
The decode()
method will always eat up all input to the end of
file.
my $decoder = new MIME::Decoder "7bit";
Returns the undefined value if no known decoders are appropriate.
if (MIME::Decoder->supported('7BIT')) { # yes, we can handle it... } else { # drop back six and punt... }
With no args, returns all the available decoders as a hash reference... where the key is the encoding name (all lowercase, like '7bit'), and the associated value is true (it happens to be the name of the class that handles the decoding, but you probably shouldn't rely on that). Hence:
my $supported = MIME::Decoder->supported; if ($supported->{7bit}) { # yes, we can handle it... } elsif ($supported->{8bit}) { # yes, we can handle it... }
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.
"use"
any other Perl modules; the following are included as part of
MIME::Decoder.
"base64"
encoding.
The name was chosen to jibe with the pre-existing MIME::Base64 utility package, which this class actually uses to translate each line.
"binary"
encoding (in other words, no encoding).
The "binary"
decoder is a special case, since it's ill-advised to read the input
line-by-line: after all, an uncompressed image file might conceivably have
loooooooooong stretches of bytes without a "\n"
among them, and we don't want to risk blowing out our core. So, we
read-and-write fixed-size chunks.
"quoted-printable"
encoding.
The name was chosen to jibe with the pre-existing MIME::QuotedPrint utility package, which this class actually uses to translate each line.
"7bit"
and "8bit"
encodings, which guarantee short lines (a maximum of 1000 characters per
line) of US-ASCII data compatible with RFC-821.
This decoder does a line-by-line pass-through from input to output, leaving the data unchanged except that an end-of-line sequence of CRLF is converted to a newline ``\n''.
MyDecoder::decode_it()
, as follows:
Your method should take as arguments the $self
object (natch), a filehandle opened for input, called $in
, and a filehandle opened for output, called $out
.
Your method should read from the input filehandle, decode this input, and
print its decoded output to the $out
filehandle. You may do this however you see fit, so long as the end result
is the same.
Your method must return either undef
(to indicate failure), or 1
(to indicate success).
require MyDecoder;
install MyDecoder "7bit"; # use MyDecoder to decode "7bit" install MyDecoder "x-foo"; # also, use MyDecoder to decode "x-foo"
base64
encoding:
package MyBase64Decoder;
@ISA = qw(MIME::Decoder); use MIME::Decoder; use MIME::Base64; # decode_it - the private decoding method sub decode_it { my ($self, $in, $out) = @_;
while (<$in>) { my $decoded = decode_base64($_); print $out $decoded; } 1; }
That's it.
The task was pretty simple because the "base64"
encoding can easily and efficiently be parsed line-by-line... as can "quoted-printable"
, and 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.
All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.