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
*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;
=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<PerlIO::Via::QuotedPrint>, is include with Perl
+5.8.0, and more example modules are available from CPAN, such as
+L<PerlIO::Via::StripHTML> and L<PerlIO::Via::Base64>. 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<not> 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]])
=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
{
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
open(my $fh, "<:Via(Hex)", "foo.hex");
=cut
-
-
-
-
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 fails');
-ok( open($fh,">Via(MIME::QuotedPrint)", $tmp), 'open QuotedPrint for output');
+ok( !open($fh,"<Via(PerlIO::Via::QuotedPrint)", $tmp), 'open QuotedPrint for input fails');
+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,"<Via(MIME::QuotedPrint)", $tmp), 'open QuotedPrint for input');
+ok( open($fh,"<Via(PerlIO::Via::QuotedPrint)", $tmp), 'open QuotedPrint for input');
{ local $/; $b = <$fh> }
ok( close($fh), "close input file");
--- /dev/null
+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 reading: $!\n";
+
+ open( my $out,'>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<PerlIO::Via>, L<MIME::QuotedPrint>, L<PerlIO::Via::Base64>, L<PerlIO::Via::MD5>,
+L<PerlIO::Via::StripHTML>.
+
+=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
--- /dev/null
+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 = <<EOD;
+This is a tést for quoted-printable text that has hàrdly any speçial characters
+in it.
+EOD
+
+my $encoded = <<EOD;
+This is a t=E9st for quoted-printable text that has h=E0rdly any spe=E7ial =
+characters
+in it.
+EOD
+
+# Create the encoded test-file
+
+ok(
+ open( my $out,'>: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'" );
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
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<PerlIO::Via> for details.
=back
=cut
-
-
-
projects / p5sagit/p5-mst-13.2.git / commitdiff