1package PerlIO::via; 2our $VERSION = '0.18'; 3require XSLoader; 4XSLoader::load(); 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 the layer is pushed as part of an C<open> call, C<PUSHED> will be called 70I<before> the actual open occurs, whether that be via C<OPEN>, C<SYSOPEN>, 71C<FDOPEN> or by letting a lower layer do the open. 72 73=item $obj->POPPED([$fh]) 74 75Optional - called when the layer is about to be removed. 76 77=item $obj->UTF8($belowFlag,[$fh]) 78 79Optional - if present it will be called immediately after PUSHED has 80returned. It should return a true value if the layer expects data to be 81UTF-8 encoded. If it returns true, the result is as if the caller had done 82 83 ":via(YourClass):utf8" 84 85If not present or if it returns false, then the stream is left with 86the UTF-8 flag clear. 87The I<$belowFlag> argument will be true if there is a layer below 88and that layer was expecting UTF-8. 89 90=item $obj->OPEN($path,$mode,[$fh]) 91 92Optional - if not present a lower layer does the open. 93If present, called for normal opens after the layer is pushed. 94This function is subject to change as there is no easy way 95to get a lower layer to do the open and then regain control. 96 97=item $obj->BINMODE([$fh]) 98 99Optional - if not present the layer is popped on binmode($fh) or when C<:raw> 100is pushed. If present it should return 0 on success, -1 on error, or undef 101to pop the layer. 102 103=item $obj->FDOPEN($fd,[$fh]) 104 105Optional - if not present a lower layer does the open. 106If present, called after the layer is pushed for opens which pass 107a numeric file descriptor. 108This function is subject to change as there is no easy way 109to get a lower layer to do the open and then regain control. 110 111=item $obj->SYSOPEN($path,$imode,$perm,[$fh]) 112 113Optional - if not present a lower layer does the open. 114If present, called after the layer is pushed for sysopen style opens 115which pass a numeric mode and permissions. 116This function is subject to change as there is no easy way 117to get a lower layer to do the open and then regain control. 118 119=item $obj->FILENO($fh) 120 121Returns a numeric value for a Unix-like file descriptor. Returns -1 if 122there isn't one. Optional. Default is fileno($fh). 123 124=item $obj->READ($buffer,$len,$fh) 125 126Returns the number of octets placed in $buffer (must be less than or 127equal to $len). Optional. Default is to use FILL instead. 128 129=item $obj->WRITE($buffer,$fh) 130 131Returns the number of octets from $buffer that have been successfully written. 132 133=item $obj->FILL($fh) 134 135Should return a string to be placed in the buffer. Optional. If not 136provided, must provide READ or reject handles open for reading in 137PUSHED. 138 139=item $obj->CLOSE($fh) 140 141Should return 0 on success, -1 on error. 142Optional. 143 144=item $obj->SEEK($posn,$whence,$fh) 145 146Should return 0 on success, -1 on error. 147Optional. Default is to fail, but that is likely to be changed 148in future. 149 150=item $obj->TELL($fh) 151 152Returns file position. 153Optional. Default to be determined. 154 155=item $obj->UNREAD($buffer,$fh) 156 157Returns the number of octets from $buffer that have been successfully 158saved to be returned on future FILL/READ calls. Optional. Default is 159to push data into a temporary layer above this one. 160 161=item $obj->FLUSH($fh) 162 163Flush any buffered write data. May possibly be called on readable 164handles too. Should return 0 on success, -1 on error. 165 166=item $obj->SETLINEBUF($fh) 167 168Optional. No return. 169 170=item $obj->CLEARERR($fh) 171 172Optional. No return. 173 174=item $obj->ERROR($fh) 175 176Optional. Returns error state. Default is no error until a mechanism 177to signal error (die?) is worked out. 178 179=item $obj->EOF($fh) 180 181Optional. Returns end-of-file state. Default is a function of the return 182value of FILL or READ. 183 184=back 185 186=head1 EXAMPLES 187 188Check the PerlIO::via:: namespace on CPAN for examples of PerlIO layers 189implemented in Perl. To give you an idea how simple the implementation of 190a PerlIO layer can look, a simple example is included here. 191 192=head2 Example - a Hexadecimal Handle 193 194Given the following module, PerlIO::via::Hex : 195 196 package PerlIO::via::Hex; 197 198 sub PUSHED 199 { 200 my ($class,$mode,$fh) = @_; 201 # When writing we buffer the data 202 my $buf = ''; 203 return bless \$buf,$class; 204 } 205 206 sub FILL 207 { 208 my ($obj,$fh) = @_; 209 my $line = <$fh>; 210 return (defined $line) ? pack("H*", $line) : undef; 211 } 212 213 sub WRITE 214 { 215 my ($obj,$buf,$fh) = @_; 216 $$obj .= unpack("H*", $buf); 217 return length($buf); 218 } 219 220 sub FLUSH 221 { 222 my ($obj,$fh) = @_; 223 print $fh $$obj or return -1; 224 $$obj = ''; 225 return 0; 226 } 227 228 1; 229 230The following code opens up an output handle that will convert any 231output to a hexadecimal dump of the output bytes: for example "A" will 232be converted to "41" (on ASCII-based machines, on EBCDIC platforms 233the "A" will become "c1") 234 235 use PerlIO::via::Hex; 236 open(my $fh, ">:via(Hex)", "foo.hex"); 237 238and the following code will read the hexdump in and convert it 239on the fly back into bytes: 240 241 open(my $fh, "<:via(Hex)", "foo.hex"); 242 243=cut 244