1package PerlIO::via; 2our $VERSION = '0.02'; 3use XSLoader (); 4XSLoader::load 'PerlIO::via'; 51; 6__END__ 7 8=head1 NAME 9 10PerlIO::via - Helper class for PerlIO layers implemented in perl 11 12=head1 SYNOPSIS 13 14 use PerlIO::via::Layer; 15 open($fh,"<:via(Layer)",...); 16 17 use Some::Other::Package; 18 open($fh,">:via(Some::Other::Package)",...); 19 20=head1 DESCRIPTION 21 22The PerlIO::via module allows you to develop PerlIO layers in Perl, without 23having to go into the nitty gritty of programming C with XS as the interface 24to Perl. 25 26One example module, L<PerlIO::via::QuotedPrint>, is included with Perl 275.8.0, and more example modules are available from CPAN, such as 28L<PerlIO::via::StripHTML> and L<PerlIO::via::Base64>. The 29PerlIO::via::StripHTML module for instance, allows you to say: 30 31 use PerlIO::via::StripHTML; 32 open( my $fh, "<:via(StripHTML)", "index.html" ); 33 my @line = <$fh>; 34 35to obtain the text of an HTML-file in an array with all the HTML-tags 36automagically removed. 37 38Please note that if the layer is created in the PerlIO::via:: namespace, it 39does B<not> have to be fully qualified. The PerlIO::via module will prefix 40the PerlIO::via:: namespace if the specified modulename does not exist as a 41fully qualified module name. 42 43=head1 EXPECTED METHODS 44 45To create a Perl module that implements a PerlIO layer in Perl (as opposed to 46in C using XS as the interface to Perl), you need to supply some of the 47following subroutines. It is recommended to create these Perl modules in the 48PerlIO::via:: namespace, so that they can easily be located on CPAN and use 49the default namespace feature of the PerlIO::via module itself. 50 51Please note that this is an area of recent development in Perl and that the 52interface described here is therefore still subject to change (and hopefully 53will have better documentation and more examples). 54 55In the method descriptions below I<$fh> will be 56a reference to a glob which can be treated as a perl file handle. 57It refers to the layer below. I<$fh> is not passed if the layer 58is at the bottom of the stack, for this reason and to maintain 59some level of "compatibility" with TIEHANDLE classes it is passed last. 60 61=over 4 62 63=item $class->PUSHED([$mode[,$fh]]) 64 65Should return an object or the class, or -1 on failure. (Compare 66TIEHANDLE.) The arguments are an optional mode string ("r", "w", 67"w+", ...) and a filehandle for the PerlIO layer below. Mandatory. 68 69When layer is pushed as part of an C<open> call, C<PUSHED> will be called 70I<before> the actual open occurs whether than be via C<OPEN>, C<SYSOPEN>, 71C<FDOPEN> or by letting lower layer do the open. 72 73=item $obj->POPPED([$fh]) 74 75Optional - layer is about to be removed. 76 77=item $obj->UTF8($bellowFlag,[$fh]) 78 79Optional - if present it will be called immediately after PUSHED has 80returned. It should return true value if the layer expects data to be 81UTF-8 encoded. If it returns true result is as if caller had done 82 83 ":via(YourClass):utf8" 84 85If not present of it it returns false, then stream is left with 86flag clear. 87The I<$bellowFlag> argument will be true if there is a layer below 88and that layer was expecting UTF-8. 89 90 91=item $obj->OPEN($path,$mode[,$fh]) 92 93Optional - if not present lower layer does open. 94If present called for normal opens after layer is pushed. 95This function is subject to change as there is no easy way 96to get lower layer to do open and then regain control. 97 98=item $obj->BINMODE([,$fh]) 99 100Optional - if not available layer is popped on binmode($fh) or when C<:raw> 101is pushed. If present it should return 0 on success -1 on error and undef 102to pop the layer. 103 104=item $obj->FDOPEN($fd[,$fh]) 105 106Optional - if not present lower layer does open. 107If present called for opens which pass a numeric file 108descriptor after layer is pushed. 109This function is subject to change as there is no easy way 110to get lower layer to do open and then regain control. 111 112=item $obj->SYSOPEN($path,$imode,$perm,[,$fh]) 113 114Optional - if not present lower layer does open. 115If present called for sysopen style opens which pass a numeric mode 116and permissions after layer is pushed. 117This function is subject to change as there is no easy way 118to get lower layer to do open and then regain control. 119 120=item $obj->FILENO($fh) 121 122Returns a numeric value for Unix-like file descriptor. Return -1 if 123there isn't one. Optional. Default is fileno($fh). 124 125=item $obj->READ($buffer,$len,$fh) 126 127Returns the number of octets placed in $buffer (must be less than or 128equal to $len). Optional. Default is to use FILL instead. 129 130=item $obj->WRITE($buffer,$fh) 131 132Returns the number of octets from buffer that have been successfully written. 133 134=item $obj->FILL($fh) 135 136Should return a string to be placed in the buffer. Optional. If not 137provided must provide READ or reject handles open for reading in 138PUSHED. 139 140=item $obj->CLOSE($fh) 141 142Should return 0 on success, -1 on error. 143Optional. 144 145=item $obj->SEEK($posn,$whence,$fh) 146 147Should return 0 on success, -1 on error. 148Optional. Default is to fail, but that is likely to be changed 149in future. 150 151=item $obj->TELL($fh) 152 153Returns file postion. 154Optional. Default to be determined. 155 156=item $obj->UNREAD($buffer,$fh) 157 158Returns the number of octets from buffer that have been successfully 159saved to be returned on future FILL/READ calls. Optional. Default is 160to push data into a temporary layer above this one. 161 162=item $obj->FLUSH($fh) 163 164Flush any buffered write data. May possibly be called on readable 165handles too. Should return 0 on success, -1 on error. 166 167=item $obj->SETLINEBUF($fh) 168 169Optional. No return. 170 171=item $obj->CLEARERR($fh) 172 173Optional. No return. 174 175=item $obj->ERROR($fh) 176 177Optional. Returns error state. Default is no error until a mechanism 178to signal error (die?) is worked out. 179 180=item $obj->EOF($fh) 181 182Optional. Returns end-of-file state. Default is function of return 183value of FILL or READ. 184 185=back 186 187=head1 EXAMPLES 188 189Check the PerlIO::via:: namespace on CPAN for examples of PerlIO layers 190implemented in Perl. To give you an idea how simple the implementation of 191a PerlIO layer can look, as simple example is included here. 192 193=head2 Example - a Hexadecimal Handle 194 195Given the following module, PerlIO::via::Hex : 196 197 package PerlIO::via::Hex; 198 199 sub PUSHED 200 { 201 my ($class,$mode,$fh) = @_; 202 # When writing we buffer the data 203 my $buf = ''; 204 return bless \$buf,$class; 205 } 206 207 sub FILL 208 { 209 my ($obj,$fh) = @_; 210 my $line = <$fh>; 211 return (defined $line) ? pack("H*", $line) : undef; 212 } 213 214 sub WRITE 215 { 216 my ($obj,$buf,$fh) = @_; 217 $$obj .= unpack("H*", $buf); 218 return length($buf); 219 } 220 221 sub FLUSH 222 { 223 my ($obj,$fh) = @_; 224 print $fh $$obj or return -1; 225 $$obj = ''; 226 return 0; 227 } 228 229 1; 230 231the following code opens up an output handle that will convert any 232output to hexadecimal dump of the output bytes: for example "A" will 233be converted to "41" (on ASCII-based machines, on EBCDIC platforms 234the "A" will become "c1") 235 236 use PerlIO::via::Hex; 237 open(my $fh, ">:via(Hex)", "foo.hex"); 238 239and the following code will read the hexdump in and convert it 240on the fly back into bytes: 241 242 open(my $fh, "<:via(Hex)", "foo.hex"); 243 244=cut 245