Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MIME::Decoder(3)      User Contributed Perl Documentation     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...

       o   Decoding a MIME-encoded stream

       o   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)

       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) = @_;
	       local $_;
	       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.

SEE ALSO
       MIME::Tools, other MIME::Decoder	subclasses.

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.

       1;

perl v5.32.0			  2017-04-05		      MIME::Decoder(3)

NAME | SYNOPSIS | DESCRIPTION | PUBLIC INTERFACE | DECODER SUBCLASSES | NOTES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MIME::Decoder&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help