1MIME::Decoder(3) User Contributed Perl Documentation MIME::Decoder(3)
2
6 MIME::Decoder - an object for decoding the body part of a MIME stream
7
9 Before reading further, you should see MIME::Tools to make sure that
10 you understand where this module fits into the grand scheme of things.
11 Go on, do it now. I'll wait.
12 Ready? Ok...
14 Decoding a data stream
16 Here's a simple filter program to read quoted-printable data from STDIN
18 (until EOF) and write the decoded data to STDOUT:
19 use MIME::Decoder;
21 $decoder = new MIME::Decoder 'quoted-printable' or die "unsupported";
23 $decoder->decode(\*STDIN, \*STDOUT);
24 Encoding a data stream
26 Here's a simple filter program to read binary data from STDIN (until
28 EOF) and write base64-encoded data to STDOUT:
29 use MIME::Decoder;
31 $decoder = new MIME::Decoder 'base64' or die "unsupported";
33 $decoder->encode(\*STDIN, \*STDOUT);
34 Non-standard encodings
36 You can write and install your own decoders so that MIME::Decoder will
38 know about them:
39 use MyBase64Decoder;
41 install MyBase64Decoder 'base64';
43 You can also test if a given encoding is supported:
45 if (supported MIME::Decoder 'x-uuencode') {
47 ### we can uuencode!
48 }
49
51 This abstract class, and its private concrete subclasses (see below)
52 provide an OO front end to the actions of...
53 · Decoding a MIME-encoded stream
55 · Encoding a raw data stream into a MIME-encoded stream.
57 The constructor for MIME::Decoder takes the name of an encoding
59 ("base64", "7bit", etc.), and returns an instance of a subclass of
60 MIME::Decoder whose "decode()" method will perform the appropriate
61 decoding action, and whose "encode()" method will perform the appropri‐
62 ate encoding action.
63
65 Standard interface
66 If all you are doing is using this class, here's all you'll need...
68 new ENCODING
70 Class method, constructor. Create and return a new decoder object
71 which can handle the given ENCODING.
72 my $decoder = new MIME::Decoder "7bit";
74 Returns the undefined value if no known decoders are appropriate.
76 best ENCODING
78 Class method, constructor. Exactly like new(), except that this
79 defaults any unsupported encoding to "binary", after raising a
80 suitable warning (it's a fatal error if there's no binary decoder).
81 my $decoder = best MIME::Decoder "x-gzip64";
83 Will either return a decoder, or a raise a fatal exception.
85 decode INSTREAM,OUTSTREAM
87 Instance method. Decode the document waiting in the input handle
88 INSTREAM, writing the decoded information to the output handle OUT‐
89 STREAM.
90 Read the section in this document on I/O handles for more informa‐
92 tion about the arguments. Note that you can still supply old-style
93 unblessed filehandles for INSTREAM and OUTSTREAM.
94 Returns true on success, throws exception on failure.
96 encode INSTREAM,OUTSTREAM
98 Instance method. Encode the document waiting in the input filehan‐
99 dle INSTREAM, writing the encoded information to the output stream
100 OUTSTREAM.
101 Read the section in this document on I/O handles for more informa‐
103 tion about the arguments. Note that you can still supply old-style
104 unblessed filehandles for INSTREAM and OUTSTREAM.
105 Returns true on success, throws exception on failure.
107 encoding
109 Instance method. Return the encoding that this object was created
110 to handle, coerced to all lowercase (e.g., "base64").
111 head [HEAD]
113 Instance method. Completely optional: some decoders need to know a
114 little about the file they are encoding/decoding; e.g., x-uu likes
115 to have the filename. The HEAD is any object which responds to
116 messages like:
117 $head->mime_attr('content-disposition.filename');
119 supported [ENCODING]
121 Class method. With one arg (an ENCODING name), returns truth if
122 that encoding is currently handled, and falsity otherwise. The
123 ENCODING will be automatically coerced to lowercase:
124 if (supported MIME::Decoder '7BIT') {
126 ### yes, we can handle it...
127 }
128 else {
129 ### drop back six and punt...
130 }
131 With no args, returns a reference to a hash of all available
133 decoders, where the key is the encoding name (all lowercase, like
134 '7bit'), and the value is true (it happens to be the name of the
135 class that handles the decoding, but you probably shouldn't rely on
136 that). You may safely modify this hash; it will not change the way
137 the module performs its lookups. Only "install" can do that.
138 Thanks to Achim Bohnet for suggesting this method.
140 Subclass interface
142 If you are writing (or installing) a new decoder subclass, there are
144 some other methods you'll need to know about:
145 decode_it INSTREAM,OUTSTREAM
147 Abstract instance method. The back-end of the decode method. It
148 takes an input handle opened for reading (INSTREAM), and an output
149 handle opened for writing (OUTSTREAM).
150 If you are writing your own decoder subclass, you must override
152 this method in your class. Your method should read from the input
153 handle via "getline()" or "read()", decode this input, and print
154 the decoded data to the output handle via "print()". You may do
155 this however you see fit, so long as the end result is the same.
156 Note that unblessed references and globrefs are automatically
158 turned into I/O handles for you by "decode()", so you don't need to
159 worry about it.
160 Your method must return either "undef" (to indicate failure), or 1
162 (to indicate success). It may also throw an exception to indicate
163 failure.
164 encode_it INSTREAM,OUTSTREAM
166 Abstract instance method. The back-end of the encode method. It
167 takes an input handle opened for reading (INSTREAM), and an output
168 handle opened for writing (OUTSTREAM).
169 If you are writing your own decoder subclass, you must override
171 this method in your class. Your method should read from the input
172 handle via "getline()" or "read()", encode this input, and print
173 the encoded data to the output handle via "print()". You may do
174 this however you see fit, so long as the end result is the same.
175 Note that unblessed references and globrefs are automatically
177 turned into I/O handles for you by "encode()", so you don't need to
178 worry about it.
179 Your method must return either "undef" (to indicate failure), or 1
181 (to indicate success). It may also throw an exception to indicate
182 failure.
183 filter IN, OUT, COMMAND...
185 Class method, utility. If your decoder involves an external pro‐
186 gram, you can invoke them easily through this method. The command
187 must be a "filter": a command that reads input from its STDIN
188 (which will come from the IN argument) and writes output to its
189 STDOUT (which will go to the OUT argument).
190 For example, here's a decoder that un-gzips its data:
192 sub decode_it {
194 my ($self, $in, $out) = @_;
195 $self->filter($in, $out, "gzip -d -");
196 }
197 The usage is similar to IPC::Open2::open2 (which it uses inter‐
199 nally), so you can specify COMMAND as a single argument or as an
200 array.
201 init ARGS...
203 Instance method. Do any necessary initialization of the new
204 instance, taking whatever arguments were given to "new()". Should
205 return the self object on success, undef on failure.
206 install ENCODINGS...
208 Class method. Install this class so that each encoding in ENCOD‐
209 INGS is handled by it:
210 install MyBase64Decoder 'base64', 'x-base64super';
212 You should not override this method.
214 uninstall ENCODINGS...
216 Class method. Uninstall support for encodings. This is a way to
217 turn off the decoding of "experimental" encodings. For safety,
218 always use MIME::Decoder directly:
219 uninstall MIME::Decoder 'x-uu', 'x-uuencode';
221 You should not override this method.
223
225 You don't need to "use" any other Perl modules; the following "stan‐
226 dard" subclasses are included as part of MIME::Decoder:
227 Class: Handles encodings:
229 ------------------------------------------------------------
230 MIME::Decoder::Binary binary
231 MIME::Decoder::NBit 7bit, 8bit
232 MIME::Decoder::Base64 base64
233 MIME::Decoder::QuotedPrint quoted-printable
234 The following "non-standard" subclasses are also included:
236 Class: Handles encodings:
238 ------------------------------------------------------------
239 MIME::Decoder::UU x-uu, x-uuencode
240 MIME::Decoder::Gzip64 x-gzip64 ** requires gzip!
241
243 Input/Output handles
244 As of MIME-tools 2.0, this class has to play nice with the new
246 MIME::Body class... which means that input and output routines cannot
247 just assume that they are dealing with filehandles.
248 Therefore, all that MIME::Decoder and its subclasses require (and,
250 thus, all that they can assume) is that INSTREAMs and OUTSTREAMs are
251 objects which respond to a subset of the messages defined in the
252 IO::Handle interface; minimally:
253 print
255 getline
256 read(BUF,NBYTES)
257 For backwards compatibilty, if you supply a scalar filehandle name
259 (like "STDOUT") or an unblessed glob reference (like "\*STDOUT") where
260 an INSTREAM or OUTSTREAM is expected, this package will automatically
261 wrap it in an object that fits these criteria, via IO::Wrap.
262 Thanks to Achim Bohnet for suggesting this more-generic I/O model.
264 Writing a decoder
266 If you're experimenting with your own encodings, you'll probably want
268 to write a decoder. Here are the basics:
269 1. Create a module, like "MyDecoder::", for your decoder. Declare it
271 to be a subclass of MIME::Decoder.
272 2. Create the following instance methods in your class, as described
274 above:
275 decode_it
277 encode_it
278 init
279 3. In your application program, activate your decoder for one or more
281 encodings like this:
282 require MyDecoder;
284 install MyDecoder "7bit"; ### use MyDecoder to decode "7bit"
286 install MyDecoder "x-foo"; ### also use MyDecoder to decode "x-foo"
287 To illustrate, here's a custom decoder class for the "quoted-printable"
289 encoding:
290 package MyQPDecoder;
292 @ISA = qw(MIME::Decoder);
294 use MIME::Decoder;
295 use MIME::QuotedPrint;
296 ### decode_it - the private decoding method
298 sub decode_it {
299 my ($self, $in, $out) = @_;
300 local $_;
301 while (defined($_ = $in->getline)) {
302 my $decoded = decode_qp($_);
303 $out->print($decoded);
304 }
305 1;
306 }
307 ### encode_it - the private encoding method
309 sub encode_it {
310 my ($self, $in, $out) = @_;
311 my ($buf, $nread) = ('', 0);
313 while ($in->read($buf, 60)) {
314 my $encoded = encode_qp($buf);
315 $out->print($encoded);
316 }
317 1;
318 }
319 That's it. The task was pretty simple because the "quoted-printable"
321 encoding can easily be converted line-by-line... as can even "7bit" and
322 "8bit" (since all these encodings guarantee short lines, with a max of
323 1000 characters). The good news is: it is very likely that it will be
324 similarly-easy to write a MIME::Decoder for any future standard encod‐
325 ings.
326 The "binary" decoder, however, really required block reads and writes:
328 see "MIME::Decoder::Binary" for details.
329
331 Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).
332 All rights reserved. This program is free software; you can redis‐
334 tribute it and/or modify it under the same terms as Perl itself.
335
337 $Revision: 1.16 $ $Date: 2006/03/17 21:03:23 $
338perl v5.8.8 2006-03-17 MIME::Decoder(3)