This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
PerlIO::via: fix compiler warning
[perl5.git] / ext / PerlIO-via / via.pm
CommitLineData
e934609f 1package PerlIO::via;
63d83481 2our $VERSION = '0.13';
da4061d3
NC
3require XSLoader;
4XSLoader::load();
e7a1fdd7
NIS
51;
6__END__
7
8=head1 NAME
9
e934609f 10PerlIO::via - Helper class for PerlIO layers implemented in perl
e7a1fdd7
NIS
11
12=head1 SYNOPSIS
13
e934609f
JH
14 use PerlIO::via::Layer;
15 open($fh,"<:via(Layer)",...);
e7a1fdd7 16
b31b80f9 17 use Some::Other::Package;
e934609f 18 open($fh,">:via(Some::Other::Package)",...);
e7a1fdd7 19
b31b80f9 20=head1 DESCRIPTION
52f3c1af 21
e934609f 22The PerlIO::via module allows you to develop PerlIO layers in Perl, without
b31b80f9
EM
23having to go into the nitty gritty of programming C with XS as the interface
24to Perl.
52f3c1af 25
385e1f9f 26One example module, L<PerlIO::via::QuotedPrint>, is included with Perl
b31b80f9 275.8.0, and more example modules are available from CPAN, such as
e934609f 28L<PerlIO::via::StripHTML> and L<PerlIO::via::Base64>. The
c990a0aa 29PerlIO::via::StripHTML module for instance, allows you to say:
b31b80f9 30
e934609f
JH
31 use PerlIO::via::StripHTML;
32 open( my $fh, "<:via(StripHTML)", "index.html" );
b31b80f9
EM
33 my @line = <$fh>;
34
35to obtain the text of an HTML-file in an array with all the HTML-tags
36automagically removed.
37
e934609f
JH
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
b31b80f9 41fully qualified module name.
e7a1fdd7 42
b31b80f9
EM
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
e934609f
JH
48PerlIO::via:: namespace, so that they can easily be located on CPAN and use
49the default namespace feature of the PerlIO::via module itself.
b31b80f9
EM
50
51Please note that this is an area of recent development in Perl and that the
c990a0aa
RGS
52interface described here is therefore still subject to change (and hopefully
53will have better documentation and more examples).
b31b80f9
EM
54
55In the method descriptions below I<$fh> will be
e7a1fdd7
NIS
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
2b8740d8 59some level of "compatibility" with TIEHANDLE classes it is passed last.
802588c3 60
e7a1fdd7
NIS
61=over 4
62
9ec269cb 63=item $class->PUSHED([$mode,[$fh]])
e7a1fdd7 64
7d61c391
JH
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.
e7a1fdd7 68
9ec269cb
LS
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.
30ef3321 72
e7a1fdd7
NIS
73=item $obj->POPPED([$fh])
74
9ec269cb 75Optional - called when the layer is about to be removed.
e7a1fdd7 76
d477ab3e 77=item $obj->UTF8($belowFlag,[$fh])
802588c3
NIS
78
79Optional - if present it will be called immediately after PUSHED has
9ec269cb
LS
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
802588c3
NIS
82
83 ":via(YourClass):utf8"
84
9ec269cb
LS
85If not present or if it returns false, then the stream is left with
86the UTF-8 flag clear.
d477ab3e 87The I<$belowFlag> argument will be true if there is a layer below
802588c3
NIS
88and that layer was expecting UTF-8.
89
9ec269cb 90=item $obj->OPEN($path,$mode,[$fh])
802588c3 91
9ec269cb
LS
92Optional - if not present a lower layer does the open.
93If present, called for normal opens after the layer is pushed.
802588c3 94This function is subject to change as there is no easy way
9ec269cb 95to get a lower layer to do the open and then regain control.
e7a1fdd7 96
9ec269cb 97=item $obj->BINMODE([$fh])
86e05cf2 98
9ec269cb
LS
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
86e05cf2
NIS
101to pop the layer.
102
9ec269cb 103=item $obj->FDOPEN($fd,[$fh])
e7a1fdd7 104
9ec269cb
LS
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.
802588c3 108This function is subject to change as there is no easy way
9ec269cb 109to get a lower layer to do the open and then regain control.
e7a1fdd7 110
9ec269cb 111=item $obj->SYSOPEN($path,$imode,$perm,[$fh])
e7a1fdd7 112
9ec269cb
LS
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.
802588c3 116This function is subject to change as there is no easy way
9ec269cb 117to get a lower layer to do the open and then regain control.
e7a1fdd7
NIS
118
119=item $obj->FILENO($fh)
120
9ec269cb 121Returns a numeric value for a Unix-like file descriptor. Returns -1 if
47bfe92f 122there isn't one. Optional. Default is fileno($fh).
e7a1fdd7
NIS
123
124=item $obj->READ($buffer,$len,$fh)
125
6391fff2
MJD
126Returns the number of octets placed in $buffer (must be less than or
127equal to $len). Optional. Default is to use FILL instead.
e7a1fdd7
NIS
128
129=item $obj->WRITE($buffer,$fh)
130
9ec269cb 131Returns the number of octets from $buffer that have been successfully written.
e7a1fdd7
NIS
132
133=item $obj->FILL($fh)
134
47bfe92f 135Should return a string to be placed in the buffer. Optional. If not
9ec269cb 136provided, must provide READ or reject handles open for reading in
47bfe92f 137PUSHED.
e7a1fdd7
NIS
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.
f74ea477
JH
147Optional. Default is to fail, but that is likely to be changed
148in future.
e7a1fdd7
NIS
149
150=item $obj->TELL($fh)
151
055cc54b 152Returns file position.
f74ea477 153Optional. Default to be determined.
e7a1fdd7
NIS
154
155=item $obj->UNREAD($buffer,$fh)
156
9ec269cb 157Returns the number of octets from $buffer that have been successfully
f74ea477 158saved to be returned on future FILL/READ calls. Optional. Default is
47bfe92f 159to push data into a temporary layer above this one.
e7a1fdd7
NIS
160
161=item $obj->FLUSH($fh)
162
47bfe92f
JH
163Flush any buffered write data. May possibly be called on readable
164handles too. Should return 0 on success, -1 on error.
e7a1fdd7
NIS
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
9ec269cb 181Optional. Returns end-of-file state. Default is a function of the return
47bfe92f 182value of FILL or READ.
e7a1fdd7
NIS
183
184=back
185
b31b80f9
EM
186=head1 EXAMPLES
187
e934609f 188Check the PerlIO::via:: namespace on CPAN for examples of PerlIO layers
b31b80f9 189implemented in Perl. To give you an idea how simple the implementation of
9ec269cb 190a PerlIO layer can look, a simple example is included here.
b31b80f9 191
a2ae6f84
JH
192=head2 Example - a Hexadecimal Handle
193
c990a0aa 194Given the following module, PerlIO::via::Hex :
a2ae6f84 195
e934609f 196 package PerlIO::via::Hex;
a2ae6f84
JH
197
198 sub PUSHED
199 {
f74ea477 200 my ($class,$mode,$fh) = @_;
a2ae6f84 201 # When writing we buffer the data
f74ea477
JH
202 my $buf = '';
203 return bless \$buf,$class;
a2ae6f84
JH
204 }
205
206 sub FILL
207 {
208 my ($obj,$fh) = @_;
209 my $line = <$fh>;
210 return (defined $line) ? pack("H*", $line) : undef;
a2ae6f84
JH
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
055cc54b 230The following code opens up an output handle that will convert any
9ec269cb 231output to a hexadecimal dump of the output bytes: for example "A" will
a2ae6f84
JH
232be converted to "41" (on ASCII-based machines, on EBCDIC platforms
233the "A" will become "c1")
234
e934609f
JH
235 use PerlIO::via::Hex;
236 open(my $fh, ">:via(Hex)", "foo.hex");
a2ae6f84
JH
237
238and the following code will read the hexdump in and convert it
239on the fly back into bytes:
240
e934609f 241 open(my $fh, "<:via(Hex)", "foo.hex");
a2ae6f84 242
e7a1fdd7 243=cut