1MIME::Decoder(3)      User Contributed Perl Documentation     MIME::Decoder(3)
2
3
4

NAME

6       MIME::Decoder - an object for decoding the body part of a MIME stream
7

SYNOPSIS

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
13       Ready?  Ok...
14
15   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
19           use MIME::Decoder;
20
21           $decoder = new MIME::Decoder 'quoted-printable' or die "unsupported";
22           $decoder->decode(\*STDIN, \*STDOUT);
23
24   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
28           use MIME::Decoder;
29
30           $decoder = new MIME::Decoder 'base64' or die "unsupported";
31           $decoder->encode(\*STDIN, \*STDOUT);
32
33   Non-standard encodings
34       You can write and install your own decoders so that MIME::Decoder will
35       know about them:
36
37           use MyBase64Decoder;
38
39           install MyBase64Decoder 'base64';
40
41       You can also test if a given encoding is supported:
42
43           if (supported MIME::Decoder 'x-uuencode') {
44               ### we can uuencode!
45           }
46

DESCRIPTION

48       This abstract class, and its private concrete subclasses (see below)
49       provide an OO front end to the actions of...
50
51       ·   Decoding a MIME-encoded stream
52
53       ·   Encoding a raw data stream into a MIME-encoded stream.
54
55       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

PUBLIC INTERFACE

62   Standard interface
63       If all you are doing is using this class, here's all you'll need...
64
65       new ENCODING
66           Class method, constructor.  Create and return a new decoder object
67           which can handle the given ENCODING.
68
69               my $decoder = new MIME::Decoder "7bit";
70
71           Returns the undefined value if no known decoders are appropriate.
72
73       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
78               my $decoder = best MIME::Decoder "x-gzip64";
79
80           Will either return a decoder, or a raise a fatal exception.
81
82       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
87           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
91           Returns true on success, throws exception on failure.
92
93       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
98           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
102           Returns true on success, throws exception on failure.
103
104       encoding
105           Instance method.  Return the encoding that this object was created
106           to handle, coerced to all lowercase (e.g., "base64").
107
108       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
114               $head->mime_attr('content-disposition.filename');
115
116       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
121               if (supported MIME::Decoder '7BIT') {
122                   ### yes, we can handle it...
123               }
124               else {
125                   ### drop back six and punt...
126               }
127
128           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
135           Thanks to Achim Bohnet for suggesting this method.
136
137   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
141       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
146           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
152           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
156           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
160       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
165           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
171           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
175           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
179       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
186           For example, here's a decoder that un-gzips its data:
187
188               sub decode_it {
189                   my ($self, $in, $out) = @_;
190                   $self->filter($in, $out, "gzip -d -");
191               }
192
193           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
197       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
202       install ENCODINGS...
203           Class method.  Install this class so that each encoding in
204           ENCODINGS is handled by it:
205
206               install MyBase64Decoder 'base64', 'x-base64super';
207
208           You should not override this method.
209
210       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
215               uninstall MIME::Decoder 'x-uu', 'x-uuencode';
216
217           You should not override this method.
218

DECODER SUBCLASSES

220       You don't need to "use" any other Perl modules; the following
221       "standard" subclasses are included as part of MIME::Decoder:
222
223            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
230       The following "non-standard" subclasses are also included:
231
232            Class:                         Handles encodings:
233            ------------------------------------------------------------
234            MIME::Decoder::UU              x-uu, x-uuencode
235            MIME::Decoder::Gzip64          x-gzip64            ** requires gzip!
236

NOTES

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
243       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
248             print
249             getline
250             read(BUF,NBYTES)
251
252       Thanks to Achim Bohnet for suggesting this more-generic I/O model.
253
254   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
258       1.  Create a module, like "MyDecoder::", for your decoder.  Declare it
259           to be a subclass of MIME::Decoder.
260
261       2.  Create the following instance methods in your class, as described
262           above:
263
264               decode_it
265               encode_it
266               init
267
268       3.  In your application program, activate your decoder for one or more
269           encodings like this:
270
271               require MyDecoder;
272
273               install MyDecoder "7bit";   ### use MyDecoder to decode "7bit"
274               install MyDecoder "x-foo";  ### also use MyDecoder to decode "x-foo"
275
276       To illustrate, here's a custom decoder class for the "quoted-printable"
277       encoding:
278
279           package MyQPDecoder;
280
281           @ISA = qw(MIME::Decoder);
282           use MIME::Decoder;
283           use MIME::QuotedPrint;
284
285           ### 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
296           ### encode_it - the private encoding method
297           sub encode_it {
298               my ($self, $in, $out) = @_;
299
300               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
308       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
315       The "binary" decoder, however, really required block reads and writes:
316       see "MIME::Decoder::Binary" for details.
317

SEE ALSO

319       MIME::Tools, other MIME::Decoder subclasses.
320

AUTHOR

322       Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).
323
324       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
327       1;
328
329
330
331perl v5.32.0                      2020-07-28                  MIME::Decoder(3)
Impressum