From: Elizabeth Mattijsen Date: Mon, 8 Jul 2002 10:21:09 +0000 (+0200) Subject: [PATCH] Removing example layers from MIME::QuotedPrint X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b31b80f9d91ded188b47dd78c18a0a1effe2584d;p=p5sagit%2Fp5-mst-13.2.git [PATCH] Removing example layers from MIME::QuotedPrint Date: Mon, 08 Jul 2002 10:21:09 +0200 Message-Id: <4.2.0.58.20020708090819.02740f00@mickey.dijkmat.nl> Subject: Re: [PATCH] Removing example layers from MIME::QuotedPrint From: Elizabeth Mattijsen Date: Tue, 09 Jul 2002 09:29:52 +0200 Message-Id: <4.2.0.58.20020709092337.02893300@mickey.dijkmat.nl> p4raw-id: //depot/perl@17449 --- diff --git a/MANIFEST b/MANIFEST index 8738cba..5b9c3cf 100644 --- a/MANIFEST +++ b/MANIFEST @@ -1359,6 +1359,8 @@ lib/overload.pm Module for overloading perl operators lib/overload.t See if operator overloading works lib/perl5db.pl Perl debugging routines lib/PerlIO.pm PerlIO support module +lib/PerlIO/Via/QuotedPrint.pm PerlIO::Via::QuotedPrint +lib/PerlIO/Via/t/QuotedPrint.t PerlIO::Via::QuotedPrint lib/ph.t See if h2ph works lib/Pod/Checker.pm Pod-Parser - check POD documents for syntax errors lib/Pod/Find.pm used by pod/splitpod diff --git a/ext/MIME/Base64/QuotedPrint.pm b/ext/MIME/Base64/QuotedPrint.pm index ad0d7e1..2cdc018 100644 --- a/ext/MIME/Base64/QuotedPrint.pm +++ b/ext/MIME/Base64/QuotedPrint.pm @@ -159,37 +159,4 @@ sub decode_qp ($) *encode = \&encode_qp; *decode = \&decode_qp; -# Methods for use as a PerlIO layer object - -sub PUSHED -{ - my ($class,$mode) = @_; - # When writing we buffer the data - my $write = ''; - return bless \$write,$class; -} - -sub FILL -{ - my ($obj,$fh) = @_; - my $line = <$fh>; - return (defined $line) ? decode_qp($line) : undef; -} - -sub WRITE -{ - my ($obj,$buf,$fh) = @_; - $$obj .= encode_qp($buf); - return length($buf); -} - -sub FLUSH -{ - my ($obj,$fh) = @_; - print $fh $$obj or return -1; - $$obj = ''; - return 0; -} - - 1; diff --git a/ext/PerlIO/Via/Via.pm b/ext/PerlIO/Via/Via.pm index 7f3938a..6c4cd48 100644 --- a/ext/PerlIO/Via/Via.pm +++ b/ext/PerlIO/Via/Via.pm @@ -11,30 +11,53 @@ PerlIO::Via - Helper class for PerlIO layers implemented in perl =head1 SYNOPSIS - use Some::Package; + use PerlIO::Via::Layer; + open($fh,"<:Via(Layer)",...); - open($fh,"<:Via(Some::Package)",...); + use Some::Other::Package; + open($fh,">:Via(Some::Other::Package)",...); - use PerlIO::Via::SomeLayer; +=head1 DESCRIPTION - # Assume PerlIO::Via:: default namespace when SomeLayer.pm is not found - open($fh,"<:Via(SomeLayer)",...); +The PerlIO::Via module allows you to develop PerlIO layers in Perl, without +having to go into the nitty gritty of programming C with XS as the interface +to Perl. -=head1 DESCRIPTION +One example module, L, is include with Perl +5.8.0, and more example modules are available from CPAN, such as +L and L. The +PerlIO::Via::StripHTML for instance, allows you to say: + + use PerlIO::Via::StripHTML; + open( my $fh, "<:Via(StripHTML)", "index.html" ); + my @line = <$fh>; + +to obtain the text of an HTML-file in an array with all the HTML-tags +automagically removed. + +Please note that if the layer is created in the PerlIO::Via:: namespace, it +does B have to be fully qualified. The PerlIO::Via module will prefix +the PerlIO::Via:: namespace if the specified modulename does not exist as a +fully qualified module name. -The package to be used as a layer should implement at least some of the -following methods. In the method descriptions below I<$fh> will be +=head1 EXPECTED METHODS + +To create a Perl module that implements a PerlIO layer in Perl (as opposed to +in C using XS as the interface to Perl), you need to supply some of the +following subroutines. It is recommended to create these Perl modules in the +PerlIO::Via:: namespace, so that they can easily be located on CPAN and use +the default namespace feature of the PerlIO::Via module itself. + +Please note that this is an area of recent development in Perl and that the +interface described here is therefor still subject to change (and hopefully +better documentation and more examples). + +In the method descriptions below I<$fh> will be a reference to a glob which can be treated as a perl file handle. It refers to the layer below. I<$fh> is not passed if the layer is at the bottom of the stack, for this reason and to maintain some level of "compatibility" with TIEHANDLE classes it is passed last. - -As an example, in Perl release 5.8.0 the included MIME::QuotedPrint -module defines the required TIEHANDLE methods so that you can say - - use MIME::QuotedPrint; - open(my $fh, ">Via(MIME::QuotedPrint)", "qp"); - + =over 4 =item $class->PUSHED([$mode[,$fh]]) @@ -147,11 +170,17 @@ value of FILL or READ. =back +=head1 EXAMPLES + +Check the PerlIO::Via:: namespace on CPAN for examples of PerlIO layers +implemented in Perl. To give you an idea how simple the implementation of +a PerlIO layer can look, as simple example is included here. + =head2 Example - a Hexadecimal Handle -Given the following module, Hex.pm: +Given the following module, PerlIO::Via::Hex.pm: - package Hex; + package PerlIO::Via::Hex; sub PUSHED { @@ -190,7 +219,7 @@ output to hexadecimal dump of the output bytes: for example "A" will be converted to "41" (on ASCII-based machines, on EBCDIC platforms the "A" will become "c1") - use Hex; + use PerlIO::Via::Hex; open(my $fh, ">:Via(Hex)", "foo.hex"); and the following code will read the hexdump in and convert it @@ -199,7 +228,3 @@ on the fly back into bytes: open(my $fh, "<:Via(Hex)", "foo.hex"); =cut - - - - diff --git a/ext/PerlIO/t/via.t b/ext/PerlIO/t/via.t index 9fe699f..85f5b8e 100644 --- a/ext/PerlIO/t/via.t +++ b/ext/PerlIO/t/via.t @@ -20,14 +20,14 @@ my $fh; my $a = join("", map { chr } 0..255) x 10; my $b; -BEGIN { use_ok('MIME::QuotedPrint'); } +BEGIN { use_ok('PerlIO::Via::QuotedPrint'); } -ok( !open($fh,"Via(MIME::QuotedPrint)", $tmp), 'open QuotedPrint for output'); +ok( !open($fh,"Via(PerlIO::Via::QuotedPrint)", $tmp), 'open QuotedPrint for output'); ok( (print $fh $a), "print to output file"); ok( close($fh), 'close output file'); -ok( open($fh," } ok( close($fh), "close input file"); diff --git a/lib/PerlIO/Via/QuotedPrint.pm b/lib/PerlIO/Via/QuotedPrint.pm new file mode 100644 index 0000000..ab3448d --- /dev/null +++ b/lib/PerlIO/Via/QuotedPrint.pm @@ -0,0 +1,87 @@ +package PerlIO::Via::QuotedPrint; + +# Make sure we do things by the book +# Set the version info + +use strict; +$PerlIO::Via::QuotedPrint::VERSION = 0.01; + +# Make sure the encoding/decoding stuff is available + +use MIME::QuotedPrint (); # no need to pollute this namespace + +#----------------------------------------------------------------------- +# IN: 1 class to bless with +# 2 mode string (ignored) +# 3 file handle of PerlIO layer below (ignored) +# OUT: 1 blessed object + +sub PUSHED { bless [],$_[0] } #PUSHED + +#----------------------------------------------------------------------- +# IN: 1 instantiated object (ignored) +# 2 handle to read from +# OUT: 1 decoded string + +sub FILL { + +# Read the line from the handle +# Decode if there is something decode and return result or signal eof + + my $line = readline( $_[1] ); + (defined $line) ? MIME::QuotedPrint::decode_qp( $line ) : undef; +} #FILL + +#----------------------------------------------------------------------- +# IN: 1 instantiated object (ignored) +# 2 buffer to be written +# 3 handle to write to +# OUT: 1 number of bytes written + +sub WRITE { + +# Encode whatever needs to be encoded and write to handle: indicate result + + (print {$_[2]} MIME::QuotedPrint::encode_qp($_[1])) ? length($_[1]) : -1; +} #WRITE + +# Satisfy -require- + +1; + +__END__ + +=head1 NAME + +PerlIO::Via::QuotedPrint - PerlIO layer for quoted-printable strings + +=head1 SYNOPSIS + + use PerlIO::Via::QuotedPrint; + + open( my $in,'Via(PerlIO::Via::QuotedPrint)','file.qp' ) + or die "Can't open file.qp for writing: $!\n"; + +=head1 DESCRIPTION + +This module implements a PerlIO layer that works on files encoded in the +quoted-printable format. It will decode from quoted-printable while reading +from a handle, and it will encode as quoted-printable while writing to a handle. + +=head1 SEE ALSO + +L, L, L, L, +L. + +=head1 COPYRIGHT + +Copyright (c) 2002 Elizabeth Mattijsen. Based on example that was initially +added to MIME::QuotedPrint.pm for the 5.8.0 distribution of Perl. + +This library is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + +=cut diff --git a/lib/PerlIO/Via/t/QuotedPrint.t b/lib/PerlIO/Via/t/QuotedPrint.t new file mode 100644 index 0000000..59d1363 --- /dev/null +++ b/lib/PerlIO/Via/t/QuotedPrint.t @@ -0,0 +1,55 @@ +my $file = 'test.qp'; + +BEGIN { + if ($ENV{PERL_CORE}) { + chdir 't' if -d 't'; + @INC = '../lib'; + } +} + +use Test::More tests => 11; + +BEGIN { use_ok('PerlIO::Via::QuotedPrint') } + +my $decoded = <:Via(PerlIO::Via::QuotedPrint)', $file ), + "opening '$file' for writing" +); + +ok( (print $out $decoded), 'print to file' ); +ok( close( $out ), 'closing encoding handle' ); + +# Check encoding without layers + +{ +local $/ = undef; +ok( open( my $test,$file ), 'opening without layer' ); +is( $encoded,readline( $test ), 'check encoded content' ); +ok( close( $test ), 'close test handle' ); +} + +# Check decoding _with_ layers + +ok( + open( my $in,'<:Via(PerlIO::Via::QuotedPrint)', $file ), + "opening '$file' for reading" +); +is( $decoded,join( '',<$in> ), 'check decoding' ); +ok( close( $in ), 'close decoding handle' ); + +# Remove whatever we created now + +ok( unlink( $file ), "remove test file '$file'" ); diff --git a/pod/perliol.pod b/pod/perliol.pod index b9dcee9..a921bc8 100644 --- a/pod/perliol.pod +++ b/pod/perliol.pod @@ -780,13 +780,13 @@ makes this layer available, although F "knows" where to find it. It is an example of a layer which takes an argument as it is called thus: - open($fh,"<:encoding(iso-8859-7)",$pathname) + open( $fh, "<:encoding(iso-8859-7)", $pathname ); =item ":Scalar" -Provides support for +Provides support for reading data from and writing data to a scalar. - open($fh,"...",\$scalar) + open( $fh, ":Scalar", \$scalar ); When a handle is so opened, then reads get bytes from the string value of I<$scalar>, and writes change the value. In both cases the position @@ -797,8 +797,8 @@ determined via C. Provided to allow layers to be implemented as Perl code. For instance: - use MIME::QuotedPrint; - open(my $fh, ">Via(MIME::QuotedPrint)", "qp"); + use PerlIO::Via::StripHTML; + open( my $fh, ">:Via(StripHTML)", "index.html" ); See L for details. @@ -867,6 +867,3 @@ a person who is not a PerlIO guru (yet). =back =cut - - -