Devil Killer Is Here MiNi Shell
MiNi SheLL

Current Path : /proc/thread-self/root/usr/local/man/man3/
Linux boscustweb5002.eigbox.net 5.4.91 #1 SMP Wed Jan 20 18:10:28 EST 2021 x86_64
Current File : //proc/thread-self/root/usr/local/man/man3/MIME::Decoder.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MIME::Decoder 3"
.TH MIME::Decoder 3 "2006-03-17" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
MIME::Decoder \- an object for decoding the body part of a MIME stream
.SH "SYNOPSIS"
.IX Header "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.
.PP
Ready?  Ok...
.Sh "Decoding a data stream"
.IX Subsection "Decoding a data stream"
Here's a simple filter program to read quoted-printable data from \s-1STDIN\s0
(until \s-1EOF\s0) and write the decoded data to \s-1STDOUT:\s0
.PP
.Vb 1
\&    use MIME::Decoder;
.Ve
.PP
.Vb 2
\&    $decoder = new MIME::Decoder 'quoted-printable' or die "unsupported";
\&    $decoder->decode(\e*STDIN, \e*STDOUT);
.Ve
.Sh "Encoding a data stream"
.IX Subsection "Encoding a data stream"
Here's a simple filter program to read binary data from \s-1STDIN\s0
(until \s-1EOF\s0) and write base64\-encoded data to \s-1STDOUT:\s0
.PP
.Vb 1
\&    use MIME::Decoder;
.Ve
.PP
.Vb 2
\&    $decoder = new MIME::Decoder 'base64' or die "unsupported";
\&    $decoder->encode(\e*STDIN, \e*STDOUT);
.Ve
.Sh "Non-standard encodings"
.IX Subsection "Non-standard encodings"
You can \fBwrite and install\fR your own decoders so that
MIME::Decoder will know about them:
.PP
.Vb 1
\&    use MyBase64Decoder;
.Ve
.PP
.Vb 1
\&    install MyBase64Decoder 'base64';
.Ve
.PP
You can also \fBtest\fR if a given encoding is supported:
.PP
.Vb 3
\&    if (supported MIME::Decoder 'x-uuencode') {
\&        ### we can uuencode!
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This abstract class, and its private concrete subclasses (see below)
provide an \s-1OO\s0 front end to the actions of...
.IP "\(bu" 4
Decoding a MIME-encoded stream
.IP "\(bu" 4
Encoding a raw data stream into a MIME-encoded stream.
.PP
The constructor for MIME::Decoder takes the name of an encoding
(\f(CW\*(C`base64\*(C'\fR, \f(CW\*(C`7bit\*(C'\fR, etc.), and returns an instance of a \fIsubclass\fR
of MIME::Decoder whose \f(CW\*(C`decode()\*(C'\fR method will perform the appropriate
decoding action, and whose \f(CW\*(C`encode()\*(C'\fR method will perform the appropriate
encoding action.
.SH "PUBLIC INTERFACE"
.IX Header "PUBLIC INTERFACE"
.Sh "Standard interface"
.IX Subsection "Standard interface"
If all you are doing is \fIusing\fR this class, here's all you'll need...
.IP "new \s-1ENCODING\s0" 4
.IX Item "new ENCODING"
\&\fIClass method, constructor.\fR
Create and return a new decoder object which can handle the
given \s-1ENCODING\s0.
.Sp
.Vb 1
\&    my $decoder = new MIME::Decoder "7bit";
.Ve
.Sp
Returns the undefined value if no known decoders are appropriate.
.IP "best \s-1ENCODING\s0" 4
.IX Item "best ENCODING"
\&\fIClass method, constructor.\fR
Exactly like \fInew()\fR, except that this defaults any unsupported encoding to
\&\*(L"binary\*(R", after raising a suitable warning (it's a fatal error if there's
no binary decoder).
.Sp
.Vb 1
\&    my $decoder = best MIME::Decoder "x-gzip64";
.Ve
.Sp
Will either return a decoder, or a raise a fatal exception.
.IP "decode \s-1INSTREAM\s0,OUTSTREAM" 4
.IX Item "decode INSTREAM,OUTSTREAM"
\&\fIInstance method.\fR
Decode the document waiting in the input handle \s-1INSTREAM\s0,
writing the decoded information to the output handle \s-1OUTSTREAM\s0.
.Sp
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 \s-1INSTREAM\s0 and \s-1OUTSTREAM\s0.
.Sp
Returns true on success, throws exception on failure.
.IP "encode \s-1INSTREAM\s0,OUTSTREAM" 4
.IX Item "encode INSTREAM,OUTSTREAM"
\&\fIInstance method.\fR
Encode the document waiting in the input filehandle \s-1INSTREAM\s0,
writing the encoded information to the output stream \s-1OUTSTREAM\s0.
.Sp
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 \s-1INSTREAM\s0 and \s-1OUTSTREAM\s0.
.Sp
Returns true on success, throws exception on failure.
.IP "encoding" 4
.IX Item "encoding"
\&\fIInstance method.\fR
Return the encoding that this object was created to handle,
coerced to all lowercase (e.g., \f(CW"base64"\fR).
.IP "head [\s-1HEAD\s0]" 4
.IX Item "head [HEAD]"
\&\fIInstance method.\fR
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 \s-1HEAD\s0 is any object which responds to messages like:
.Sp
.Vb 1
\&    $head->mime_attr('content-disposition.filename');
.Ve
.IP "supported [\s-1ENCODING\s0]" 4
.IX Item "supported [ENCODING]"
\&\fIClass method.\fR
With one arg (an \s-1ENCODING\s0 name), returns truth if that encoding
is currently handled, and falsity otherwise.  The \s-1ENCODING\s0 will
be automatically coerced to lowercase:
.Sp
.Vb 6
\&    if (supported MIME::Decoder '7BIT') {
\&        ### yes, we can handle it...
\&    }
\&    else {
\&        ### drop back six and punt...
\&    }
.Ve
.Sp
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 \fInot\fR change the way the
module performs its lookups.  Only \f(CW\*(C`install\*(C'\fR can do that.
.Sp
\&\fIThanks to Achim Bohnet for suggesting this method.\fR
.Sh "Subclass interface"
.IX Subsection "Subclass interface"
If you are writing (or installing) a new decoder subclass, there
are some other methods you'll need to know about:
.IP "decode_it \s-1INSTREAM\s0,OUTSTREAM" 4
.IX Item "decode_it INSTREAM,OUTSTREAM"
\&\fIAbstract instance method.\fR
The back-end of the \fBdecode\fR method.  It takes an input handle
opened for reading (\s-1INSTREAM\s0), and an output handle opened for
writing (\s-1OUTSTREAM\s0).
.Sp
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 \f(CW\*(C`getline()\*(C'\fR or \f(CW\*(C`read()\*(C'\fR, decode this input, and print the
decoded data to the output handle via \f(CW\*(C`print()\*(C'\fR.  You may do this
however you see fit, so long as the end result is the same.
.Sp
Note that unblessed references and globrefs are automatically turned
into I/O handles for you by \f(CW\*(C`decode()\*(C'\fR, so you don't need to worry
about it.
.Sp
Your method must return either \f(CW\*(C`undef\*(C'\fR (to indicate failure),
or \f(CW1\fR (to indicate success).
It may also throw an exception to indicate failure.
.IP "encode_it \s-1INSTREAM\s0,OUTSTREAM" 4
.IX Item "encode_it INSTREAM,OUTSTREAM"
\&\fIAbstract instance method.\fR
The back-end of the \fBencode\fR method.  It takes an input handle
opened for reading (\s-1INSTREAM\s0), and an output handle opened for
writing (\s-1OUTSTREAM\s0).
.Sp
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 \f(CW\*(C`getline()\*(C'\fR or \f(CW\*(C`read()\*(C'\fR, encode this input, and print the
encoded data to the output handle via \f(CW\*(C`print()\*(C'\fR.  You may do this
however you see fit, so long as the end result is the same.
.Sp
Note that unblessed references and globrefs are automatically turned
into I/O handles for you by \f(CW\*(C`encode()\*(C'\fR, so you don't need to worry
about it.
.Sp
Your method must return either \f(CW\*(C`undef\*(C'\fR (to indicate failure),
or \f(CW1\fR (to indicate success).
It may also throw an exception to indicate failure.
.IP "filter \s-1IN\s0, \s-1OUT\s0, \s-1COMMAND\s0..." 4
.IX Item "filter IN, OUT, COMMAND..."
\&\fIClass method, utility.\fR
If your decoder involves an external program, you can invoke
them easily through this method.  The command must be a \*(L"filter\*(R": a
command that reads input from its \s-1STDIN\s0 (which will come from the \s-1IN\s0 argument)
and writes output to its \s-1STDOUT\s0 (which will go to the \s-1OUT\s0 argument).
.Sp
For example, here's a decoder that un-gzips its data:
.Sp
.Vb 4
\&    sub decode_it {
\&        my ($self, $in, $out) = @_;
\&        $self->filter($in, $out, "gzip -d -");
\&    }
.Ve
.Sp
The usage is similar to IPC::Open2::open2 (which it uses internally),
so you can specify \s-1COMMAND\s0 as a single argument or as an array.
.IP "init \s-1ARGS\s0..." 4
.IX Item "init ARGS..."
\&\fIInstance method.\fR
Do any necessary initialization of the new instance,
taking whatever arguments were given to \f(CW\*(C`new()\*(C'\fR.
Should return the self object on success, undef on failure.
.IP "install \s-1ENCODINGS\s0..." 4
.IX Item "install ENCODINGS..."
\&\fIClass method\fR.
Install this class so that each encoding in \s-1ENCODINGS\s0 is handled by it:
.Sp
.Vb 1
\&    install MyBase64Decoder 'base64', 'x-base64super';
.Ve
.Sp
You should not override this method.
.IP "uninstall \s-1ENCODINGS\s0..." 4
.IX Item "uninstall ENCODINGS..."
\&\fIClass method\fR.
Uninstall support for encodings.  This is a way to turn off the decoding
of \*(L"experimental\*(R" encodings.  For safety, always use MIME::Decoder directly:
.Sp
.Vb 1
\&    uninstall MIME::Decoder 'x-uu', 'x-uuencode';
.Ve
.Sp
You should not override this method.
.SH "DECODER SUBCLASSES"
.IX Header "DECODER SUBCLASSES"
You don't need to \f(CW"use"\fR any other Perl modules; the
following \*(L"standard\*(R" subclasses are included as part of MIME::Decoder:
.PP
.Vb 6
\&     Class:                         Handles encodings:
\&     ------------------------------------------------------------
\&     MIME::Decoder::Binary          binary
\&     MIME::Decoder::NBit            7bit, 8bit
\&     MIME::Decoder::Base64          base64
\&     MIME::Decoder::QuotedPrint     quoted-printable
.Ve
.PP
The following \*(L"non\-standard\*(R" subclasses are also included:
.PP
.Vb 4
\&     Class:                         Handles encodings:
\&     ------------------------------------------------------------
\&     MIME::Decoder::UU              x-uu, x-uuencode
\&     MIME::Decoder::Gzip64          x-gzip64            ** requires gzip!
.Ve
.SH "NOTES"
.IX Header "NOTES"
.Sh "Input/Output handles"
.IX Subsection "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.
.PP
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:
.PP
.Vb 3
\&      print
\&      getline
\&      read(BUF,NBYTES)
.Ve
.PP
For backwards compatibilty, if you supply a scalar filehandle name
(like \f(CW"STDOUT"\fR) or an unblessed glob reference (like \f(CW\*(C`\e*STDOUT\*(C'\fR)
where an \s-1INSTREAM\s0 or \s-1OUTSTREAM\s0 is expected, this package will
automatically wrap it in an object that fits these criteria, via IO::Wrap.
.PP
\&\fIThanks to Achim Bohnet for suggesting this more-generic I/O model.\fR
.Sh "Writing a decoder"
.IX Subsection "Writing a decoder"
If you're experimenting with your own encodings, you'll probably want
to write a decoder.  Here are the basics:
.IP "1." 4
Create a module, like \*(L"MyDecoder::\*(R", for your decoder.
Declare it to be a subclass of MIME::Decoder.
.IP "2." 4
Create the following instance methods in your class, as described above:
.Sp
.Vb 3
\&    decode_it
\&    encode_it
\&    init
.Ve
.IP "3." 4
In your application program, activate your decoder for one or
more encodings like this:
.Sp
.Vb 1
\&    require MyDecoder;
.Ve
.Sp
.Vb 2
\&    install MyDecoder "7bit";   ### use MyDecoder to decode "7bit"
\&    install MyDecoder "x-foo";  ### also use MyDecoder to decode "x-foo"
.Ve
.PP
To illustrate, here's a custom decoder class for the \f(CW\*(C`quoted\-printable\*(C'\fR
encoding:
.PP
.Vb 1
\&    package MyQPDecoder;
.Ve
.PP
.Vb 3
\&    @ISA = qw(MIME::Decoder);
\&    use MIME::Decoder;
\&    use MIME::QuotedPrint;
.Ve
.PP
.Vb 10
\&    ### 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;
\&    }
.Ve
.PP
.Vb 3
\&    ### encode_it - the private encoding method
\&    sub encode_it {
\&        my ($self, $in, $out) = @_;
.Ve
.PP
.Vb 7
\&        my ($buf, $nread) = ('', 0);
\&        while ($in->read($buf, 60)) {
\&            my $encoded = encode_qp($buf);
\&            $out->print($encoded);
\&        }
\&        1;
\&    }
.Ve
.PP
That's it.  The task was pretty simple because the \f(CW"quoted\-printable"\fR
encoding can easily be converted line\-by\-line... as can
even \f(CW"7bit"\fR and \f(CW"8bit"\fR (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.
.PP
The \f(CW"binary"\fR decoder, however, really required block reads and writes:
see \*(L"MIME::Decoder::Binary\*(R" for details.
.SH "AUTHOR"
.IX Header "AUTHOR"
Eryq (\fIeryq@zeegee.com\fR), ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
.PP
All rights reserved.  This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.SH "VERSION"
.IX Header "VERSION"
$Revision: 1.16 $ \f(CW$Date:\fR 2006/03/17 21:03:23 $
Creat By MiNi SheLL
Email: devilkiller@gmail.com