This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Minor tweak to via
[perl5.git] / ext / PerlIO / via / via.pm
CommitLineData
e934609f 1package PerlIO::via;
802588c3 2our $VERSION = '0.02';
e7a1fdd7 3use XSLoader ();
e934609f 4XSLoader::load 'PerlIO::via';
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
7d61c391 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
802588c3 69When layer is pushed as part of an C<open> call, C<PUSHED> will be called
30ef3321 70I<before> the actual open occurs whether than be via C<OPEN>, C<SYSOPEN>,
802588c3 71C<FDOPEN> or by letting lower layer do the open.
30ef3321 72
e7a1fdd7
NIS
73=item $obj->POPPED([$fh])
74
75Optional - layer is about to be removed.
76
802588c3
NIS
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
30ef3321 91=item $obj->OPEN($path,$mode[,$fh])
e7a1fdd7 92
30ef3321
NIS
93Optional - if not present lower layer does open.
94If present called for normal opens after layer is pushed.
802588c3 95This function is subject to change as there is no easy way
30ef3321 96to get lower layer to do open and then regain control.
e7a1fdd7 97
86e05cf2
NIS
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
30ef3321 104=item $obj->FDOPEN($fd[,$fh])
e7a1fdd7 105
30ef3321 106Optional - if not present lower layer does open.
802588c3
NIS
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
30ef3321 110to get lower layer to do open and then regain control.
e7a1fdd7 111
30ef3321 112=item $obj->SYSOPEN($path,$imode,$perm,[,$fh])
e7a1fdd7 113
30ef3321 114Optional - if not present lower layer does open.
802588c3 115If present called for sysopen style opens which pass a numeric mode
30ef3321 116and permissions after layer is pushed.
802588c3 117This function is subject to change as there is no easy way
30ef3321 118to get lower layer to do open and then regain control.
e7a1fdd7
NIS
119
120=item $obj->FILENO($fh)
121
47bfe92f
JH
122Returns a numeric value for Unix-like file descriptor. Return -1 if
123there isn't one. Optional. Default is fileno($fh).
e7a1fdd7
NIS
124
125=item $obj->READ($buffer,$len,$fh)
126
6391fff2
MJD
127Returns the number of octets placed in $buffer (must be less than or
128equal to $len). Optional. Default is to use FILL instead.
e7a1fdd7
NIS
129
130=item $obj->WRITE($buffer,$fh)
131
a6d05634 132Returns the number of octets from buffer that have been successfully written.
e7a1fdd7
NIS
133
134=item $obj->FILL($fh)
135
47bfe92f
JH
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.
e7a1fdd7
NIS
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.
f74ea477
JH
148Optional. Default is to fail, but that is likely to be changed
149in future.
e7a1fdd7
NIS
150
151=item $obj->TELL($fh)
152
153Returns file postion.
f74ea477 154Optional. Default to be determined.
e7a1fdd7
NIS
155
156=item $obj->UNREAD($buffer,$fh)
157
a6d05634 158Returns the number of octets from buffer that have been successfully
f74ea477 159saved to be returned on future FILL/READ calls. Optional. Default is
47bfe92f 160to push data into a temporary layer above this one.
e7a1fdd7
NIS
161
162=item $obj->FLUSH($fh)
163
47bfe92f
JH
164Flush any buffered write data. May possibly be called on readable
165handles too. Should return 0 on success, -1 on error.
e7a1fdd7
NIS
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
47bfe92f
JH
182Optional. Returns end-of-file state. Default is function of return
183value of FILL or READ.
e7a1fdd7
NIS
184
185=back
186
b31b80f9
EM
187=head1 EXAMPLES
188
e934609f 189Check the PerlIO::via:: namespace on CPAN for examples of PerlIO layers
b31b80f9
EM
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
a2ae6f84
JH
193=head2 Example - a Hexadecimal Handle
194
c990a0aa 195Given the following module, PerlIO::via::Hex :
a2ae6f84 196
e934609f 197 package PerlIO::via::Hex;
a2ae6f84
JH
198
199 sub PUSHED
200 {
f74ea477 201 my ($class,$mode,$fh) = @_;
a2ae6f84 202 # When writing we buffer the data
f74ea477
JH
203 my $buf = '';
204 return bless \$buf,$class;
a2ae6f84
JH
205 }
206
207 sub FILL
208 {
209 my ($obj,$fh) = @_;
210 my $line = <$fh>;
211 return (defined $line) ? pack("H*", $line) : undef;
a2ae6f84
JH
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
e934609f
JH
236 use PerlIO::via::Hex;
237 open(my $fh, ">:via(Hex)", "foo.hex");
a2ae6f84
JH
238
239and the following code will read the hexdump in and convert it
240on the fly back into bytes:
241
e934609f 242 open(my $fh, "<:via(Hex)", "foo.hex");
a2ae6f84 243
e7a1fdd7 244=cut