 |
Index for
Section 3 |
|
 |
Alphabetical
listing for M |
|
 |
Bottom of
page |
|
MIME::Decoder(3)
NAME
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 module fits into the grand scheme of things. Go on,
do it now. I'll wait.
Ready? Ok...
Decoding a data stream
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);
Encoding a data stream
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);
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:
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.
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).
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.
init ARGS...
Instance method. Do any necessary initialization of the new instance,
taking whatever arguments were given to "new()". Should return the
self object on success, undef on failure.
install ENCODINGS...
Class method. Install this class so that each encoding in ENCODINGS is
handled by it:
install MyBase64Decoder 'base64', 'x-base64super';
You should not override this method.
uninstall ENCODINGS...
Class method. Uninstall support for encodings. This is a way to turn
off the decoding of "experimental" encodings. For safety, always use
MIME::Decoder directly:
uninstall MIME::Decoder 'x-uu', 'x-uuencode';
You should not override this method.
DECODER SUBCLASSES
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!
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)
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.
Writing a decoder
If you're experimenting with your own encodings, you'll probably want to
write a decoder. Here are the basics:
1. Create a module, like "MyDecoder::", for your decoder. Declare it to
be a subclass of MIME::Decoder.
2. Create the following instance methods in your class, as described
above:
decode_it
encode_it
init
3. 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.
AUTHOR
Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).
All rights reserved. This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
VERSION
$Revision: 1.12 $ $Date: 2005/01/13 19:23:15 $
|
Index for
Section 3 |
|
|
Alphabetical
listing for M |
|
 |
Top of
page |
|