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
17 (until EOF) and write the decoded data to STDOUT:
18 use MIME::Decoder;
20 $decoder = new MIME::Decoder 'quoted-printable' or die "unsupported";
22 $decoder->decode(\*STDIN, \*STDOUT);
23 Encoding a data stream
25 Here's a simple filter program to read binary data from STDIN (until
26 EOF) and write base64-encoded data to STDOUT:
27 use MIME::Decoder;
29 $decoder = new MIME::Decoder 'base64' or die "unsupported";
31 $decoder->encode(\*STDIN, \*STDOUT);
32 Non-standard encodings
34 You can write and install your own decoders so that MIME::Decoder will
35 know about them:
36 use MyBase64Decoder;
38 install MyBase64Decoder 'base64';
40 You can also test if a given encoding is supported:
42 if (supported MIME::Decoder 'x-uuencode') {
44 ### we can uuencode!
45 }
46
48 This abstract class, and its private concrete subclasses (see below)
49 provide an OO front end to the actions of...
50 • Decoding a MIME-encoded stream
52 • Encoding a raw data stream into a MIME-encoded stream.
54 The constructor for MIME::Decoder takes the name of an encoding
56 ("base64", "7bit", etc.), and returns an instance of a subclass of
57 MIME::Decoder whose "decode()" method will perform the appropriate
58 decoding action, and whose "encode()" method will perform the
59 appropriate encoding action.
60
62 Standard interface
63 If all you are doing is using this class, here's all you'll need...
64 new ENCODING
66 Class method, constructor. Create and return a new decoder object
67 which can handle the given ENCODING.
68 my $decoder = new MIME::Decoder "7bit";
70 Returns the undefined value if no known decoders are appropriate.
72 best ENCODING
74 Class method, constructor. Exactly like new(), except that this
75 defaults any unsupported encoding to "binary", after raising a
76 suitable warning (it's a fatal error if there's no binary decoder).
77 my $decoder = best MIME::Decoder "x-gzip64";
79 Will either return a decoder, or a raise a fatal exception.
81 decode INSTREAM,OUTSTREAM
83 Instance method. Decode the document waiting in the input handle
84 INSTREAM, writing the decoded information to the output handle
85 OUTSTREAM.
86 Read the section in this document on I/O handles for more
88 information about the arguments. Note that you can still supply
89 old-style unblessed filehandles for INSTREAM and OUTSTREAM.
90 Returns true on success, throws exception on failure.
92 encode INSTREAM,OUTSTREAM
94 Instance method. Encode the document waiting in the input
95 filehandle INSTREAM, writing the encoded information to the output
96 stream OUTSTREAM.
97 Read the section in this document on I/O handles for more
99 information about the arguments. Note that you can still supply
100 old-style unblessed filehandles for INSTREAM and OUTSTREAM.
101 Returns true on success, throws exception on failure.
103 encoding
105 Instance method. Return the encoding that this object was created
106 to handle, coerced to all lowercase (e.g., "base64").
107 head [HEAD]
109 Instance method. Completely optional: some decoders need to know a
110 little about the file they are encoding/decoding; e.g., x-uu likes
111 to have the filename. The HEAD is any object which responds to
112 messages like:
113 $head->mime_attr('content-disposition.filename');
115 supported [ENCODING]
117 Class method. With one arg (an ENCODING name), returns truth if
118 that encoding is currently handled, and falsity otherwise. The
119 ENCODING will be automatically coerced to lowercase:
120 if (supported MIME::Decoder '7BIT') {
122 ### yes, we can handle it...
123 }
124 else {
125 ### drop back six and punt...
126 }
127 With no args, returns a reference to a hash of all available
129 decoders, where the key is the encoding name (all lowercase, like
130 '7bit'), and the value is true (it happens to be the name of the
131 class that handles the decoding, but you probably shouldn't rely on
132 that). You may safely modify this hash; it will not change the way
133 the module performs its lookups. Only "install" can do that.
134 Thanks to Achim Bohnet for suggesting this method.
136 Subclass interface
138 If you are writing (or installing) a new decoder subclass, there are
139 some other methods you'll need to know about:
140 decode_it INSTREAM,OUTSTREAM
142 Abstract instance method. The back-end of the decode method. It
143 takes an input handle opened for reading (INSTREAM), and an output
144 handle opened for writing (OUTSTREAM).
145 If you are writing your own decoder subclass, you must override
147 this method in your class. Your method should read from the input
148 handle via "getline()" or "read()", decode this input, and print
149 the decoded data to the output handle via "print()". You may do
150 this however you see fit, so long as the end result is the same.
151 Note that unblessed references and globrefs are automatically
153 turned into I/O handles for you by "decode()", so you don't need to
154 worry about it.
155 Your method must return either "undef" (to indicate failure), or 1
157 (to indicate success). It may also throw an exception to indicate
158 failure.
159 encode_it INSTREAM,OUTSTREAM
161 Abstract instance method. The back-end of the encode method. It
162 takes an input handle opened for reading (INSTREAM), and an output
163 handle opened for writing (OUTSTREAM).
164 If you are writing your own decoder subclass, you must override
166 this method in your class. Your method should read from the input
167 handle via "getline()" or "read()", encode this input, and print
168 the encoded data to the output handle via "print()". You may do
169 this however you see fit, so long as the end result is the same.
170 Note that unblessed references and globrefs are automatically
172 turned into I/O handles for you by "encode()", so you don't need to
173 worry about it.
174 Your method must return either "undef" (to indicate failure), or 1
176 (to indicate success). It may also throw an exception to indicate
177 failure.
178 filter IN, OUT, COMMAND...
180 Class method, utility. If your decoder involves an external
181 program, you can invoke them easily through this method. The
182 command must be a "filter": a command that reads input from its
183 STDIN (which will come from the IN argument) and writes output to
184 its STDOUT (which will go to the OUT argument).
185 For example, here's a decoder that un-gzips its data:
187 sub decode_it {
189 my ($self, $in, $out) = @_;
190 $self->filter($in, $out, "gzip -d -");
191 }
192 The usage is similar to IPC::Open2::open2 (which it uses
194 internally), so you can specify COMMAND as a single argument or as
195 an array.
196 init ARGS...
198 Instance method. Do any necessary initialization of the new
199 instance, taking whatever arguments were given to "new()". Should
200 return the self object on success, undef on failure.
201 install ENCODINGS...
203 Class method. Install this class so that each encoding in
204 ENCODINGS is handled by it:
205 install MyBase64Decoder 'base64', 'x-base64super';
207 You should not override this method.
209 uninstall ENCODINGS...
211 Class method. Uninstall support for encodings. This is a way to
212 turn off the decoding of "experimental" encodings. For safety,
213 always use MIME::Decoder directly:
214 uninstall MIME::Decoder 'x-uu', 'x-uuencode';
216 You should not override this method.
218
220 You don't need to "use" any other Perl modules; the following
221 "standard" subclasses are included as part of MIME::Decoder:
222 Class: Handles encodings:
224 ------------------------------------------------------------
225 MIME::Decoder::Binary binary
226 MIME::Decoder::NBit 7bit, 8bit
227 MIME::Decoder::Base64 base64
228 MIME::Decoder::QuotedPrint quoted-printable
229 The following "non-standard" subclasses are also included:
231 Class: Handles encodings:
233 ------------------------------------------------------------
234 MIME::Decoder::UU x-uu, x-uuencode
235 MIME::Decoder::Gzip64 x-gzip64 ** requires gzip!
236
238 Input/Output handles
239 As of MIME-tools 2.0, this class has to play nice with the new
240 MIME::Body class... which means that input and output routines cannot
241 just assume that they are dealing with filehandles.
242 Therefore, all that MIME::Decoder and its subclasses require (and,
244 thus, all that they can assume) is that INSTREAMs and OUTSTREAMs are
245 objects which respond to a subset of the messages defined in the
246 IO::Handle interface; minimally:
247 print
249 getline
250 read(BUF,NBYTES)
251 Thanks to Achim Bohnet for suggesting this more-generic I/O model.
253 Writing a decoder
255 If you're experimenting with your own encodings, you'll probably want
256 to write a decoder. Here are the basics:
257 1. Create a module, like "MyDecoder::", for your decoder. Declare it
259 to be a subclass of MIME::Decoder.
260 2. Create the following instance methods in your class, as described
262 above:
263 decode_it
265 encode_it
266 init
267 3. In your application program, activate your decoder for one or more
269 encodings like this:
270 require MyDecoder;
272 install MyDecoder "7bit"; ### use MyDecoder to decode "7bit"
274 install MyDecoder "x-foo"; ### also use MyDecoder to decode "x-foo"
275 To illustrate, here's a custom decoder class for the "quoted-printable"
277 encoding:
278 package MyQPDecoder;
280 @ISA = qw(MIME::Decoder);
282 use MIME::Decoder;
283 use MIME::QuotedPrint;
284 ### decode_it - the private decoding method
286 sub decode_it {
287 my ($self, $in, $out) = @_;
288 local $_;
289 while (defined($_ = $in->getline)) {
290 my $decoded = decode_qp($_);
291 $out->print($decoded);
292 }
293 1;
294 }
295 ### encode_it - the private encoding method
297 sub encode_it {
298 my ($self, $in, $out) = @_;
299 my ($buf, $nread) = ('', 0);
301 while ($in->read($buf, 60)) {
302 my $encoded = encode_qp($buf);
303 $out->print($encoded);
304 }
305 1;
306 }
307 That's it. The task was pretty simple because the "quoted-printable"
309 encoding can easily be converted line-by-line... as can even "7bit" and
310 "8bit" (since all these encodings guarantee short lines, with a max of
311 1000 characters). The good news is: it is very likely that it will be
312 similarly-easy to write a MIME::Decoder for any future standard
313 encodings.
314 The "binary" decoder, however, really required block reads and writes:
316 see "MIME::Decoder::Binary" for details.
317
319 MIME::Tools, other MIME::Decoder subclasses.
320
322 Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).
323 All rights reserved. This program is free software; you can
325 redistribute it and/or modify it under the same terms as Perl itself.
326 1;
328perl v5.34.0 2022-01-21 MIME::Decoder(3)