1package PerlIO::via; 2our $VERSION = '0.19'; 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 undef to 127indicate an error or a non-negative integer less than or equal to the 128minimum of $len and the length of the updated $buffer). Optional. 129Default is to use FILL instead. 130 131=item $obj->WRITE($buffer,$fh) 132 133Returns the number of octets from $buffer that have been successfully written. 134 135=item $obj->FILL($fh) 136 137Should return a string to be placed in the buffer. Optional. If not 138provided, must provide READ or reject handles open for reading in 139PUSHED. 140 141=item $obj->CLOSE($fh) 142 143Should return 0 on success, -1 on error. 144Optional. 145 146=item $obj->SEEK($posn,$whence,$fh) 147 148Should return 0 on success, -1 on error. 149Optional. Default is to fail, but that is likely to be changed 150in future. 151 152=item $obj->TELL($fh) 153 154Returns file position. 155Optional. Default to be determined. 156 157=item $obj->UNREAD($buffer,$fh) 158 159Returns the number of octets from $buffer that have been successfully 160saved to be returned on future FILL/READ calls. Optional. Default is 161to push data into a temporary layer above this one. 162 163=item $obj->FLUSH($fh) 164 165Flush any buffered write data. May possibly be called on readable 166handles too. Should return 0 on success, -1 on error. 167 168=item $obj->SETLINEBUF($fh) 169 170Optional. No return. 171 172=item $obj->CLEARERR($fh) 173 174Optional. No return. 175 176=item $obj->ERROR($fh) 177 178Optional. Returns error state. Default is no error until a mechanism 179to signal error (die?) is worked out. 180 181=item $obj->EOF($fh) 182 183Optional. Returns end-of-file state. Default is a function of the return 184value of FILL or READ. 185 186=back 187 188=head1 EXAMPLES 189 190Check the PerlIO::via:: namespace on CPAN for examples of PerlIO layers 191implemented in Perl. To give you an idea how simple the implementation of 192a PerlIO layer can look, a simple example is included here. 193 194=head2 Example - a Hexadecimal Handle 195 196Given the following module, PerlIO::via::Hex : 197 198 package PerlIO::via::Hex; 199 200 sub PUSHED 201 { 202 my ($class,$mode,$fh) = @_; 203 # When writing we buffer the data 204 my $buf = ''; 205 return bless \$buf,$class; 206 } 207 208 sub FILL 209 { 210 my ($obj,$fh) = @_; 211 my $line = <$fh>; 212 return (defined $line) ? pack("H*", $line) : undef; 213 } 214 215 sub WRITE 216 { 217 my ($obj,$buf,$fh) = @_; 218 $$obj .= unpack("H*", $buf); 219 return length($buf); 220 } 221 222 sub FLUSH 223 { 224 my ($obj,$fh) = @_; 225 print $fh $$obj or return -1; 226 $$obj = ''; 227 return 0; 228 } 229 230 1; 231 232The following code opens up an output handle that will convert any 233output to a hexadecimal dump of the output bytes: for example "A" will 234be converted to "41" (on ASCII-based machines, on EBCDIC platforms 235the "A" will become "c1") 236 237 use PerlIO::via::Hex; 238 open(my $fh, ">:via(Hex)", "foo.hex"); 239 240and the following code will read the hexdump in and convert it 241on the fly back into bytes: 242 243 open(my $fh, "<:via(Hex)", "foo.hex"); 244 245=cut 246