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