This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate perlio:
[perl5.git] / ext / PerlIO / Via / Via.pm
CommitLineData
e7a1fdd7
NIS
1package PerlIO::Via;
2our $VERSION = '0.01';
3use XSLoader ();
4XSLoader::load 'PerlIO::Via';
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 Some::Package;
15
16 open($fh,"<:Via(Some::Package)",...);
17
52f3c1af
RGS
18 use PerlIO::Via::SomeLayer;
19
20 # Assume PerlIO::Via:: default namespace when SomeLayer.pm is not found
21 open($fh,"<:Via(SomeLayer)",...);
22
e7a1fdd7
NIS
23=head1 DESCRIPTION
24
25The package to be used as a layer should implement at least some of the
26following methods. In the method descriptions below I<$fh> will be
27a reference to a glob which can be treated as a perl file handle.
28It refers to the layer below. I<$fh> is not passed if the layer
29is at the bottom of the stack, for this reason and to maintain
2b8740d8
JH
30some level of "compatibility" with TIEHANDLE classes it is passed last.
31
f74ea477
JH
32As an example, in Perl release 5.8.0 the included MIME::QuotedPrint
33module defines the required TIEHANDLE methods so that you can say
2b8740d8
JH
34
35 use MIME::QuotedPrint;
36 open(my $fh, ">Via(MIME::QuotedPrint)", "qp");
e7a1fdd7
NIS
37
38=over 4
39
7d61c391 40=item $class->PUSHED([$mode[,$fh]])
e7a1fdd7 41
7d61c391
JH
42Should return an object or the class, or -1 on failure. (Compare
43TIEHANDLE.) The arguments are an optional mode string ("r", "w",
44"w+", ...) and a filehandle for the PerlIO layer below. Mandatory.
e7a1fdd7 45
30ef3321
NIS
46When layer is pushed as part of an C<open> call, C<PUSHED> will be called
47I<before> the actual open occurs whether than be via C<OPEN>, C<SYSOPEN>,
48C<FDOPEN> or by letting lower layer do the open.
49
e7a1fdd7
NIS
50=item $obj->POPPED([$fh])
51
52Optional - layer is about to be removed.
53
30ef3321 54=item $obj->OPEN($path,$mode[,$fh])
e7a1fdd7 55
30ef3321
NIS
56Optional - if not present lower layer does open.
57If present called for normal opens after layer is pushed.
58This function is subject to change as there is no easy way
59to get lower layer to do open and then regain control.
e7a1fdd7 60
86e05cf2
NIS
61=item $obj->BINMODE([,$fh])
62
63Optional - if not available layer is popped on binmode($fh) or when C<:raw>
64is pushed. If present it should return 0 on success -1 on error and undef
65to pop the layer.
66
30ef3321 67=item $obj->FDOPEN($fd[,$fh])
e7a1fdd7 68
30ef3321
NIS
69Optional - if not present lower layer does open.
70If present called for opens which pass a numeric file
71descriptor after layer is pushed.
72This function is subject to change as there is no easy way
73to get lower layer to do open and then regain control.
e7a1fdd7 74
30ef3321 75=item $obj->SYSOPEN($path,$imode,$perm,[,$fh])
e7a1fdd7 76
30ef3321
NIS
77Optional - if not present lower layer does open.
78If present called for sysopen style opens which pass a numeric mode
79and permissions after layer is pushed.
80This function is subject to change as there is no easy way
81to get lower layer to do open and then regain control.
e7a1fdd7
NIS
82
83=item $obj->FILENO($fh)
84
47bfe92f
JH
85Returns a numeric value for Unix-like file descriptor. Return -1 if
86there isn't one. Optional. Default is fileno($fh).
e7a1fdd7
NIS
87
88=item $obj->READ($buffer,$len,$fh)
89
6391fff2
MJD
90Returns the number of octets placed in $buffer (must be less than or
91equal to $len). Optional. Default is to use FILL instead.
e7a1fdd7
NIS
92
93=item $obj->WRITE($buffer,$fh)
94
95Returns the number of octets from buffer that have been sucessfully written.
96
97=item $obj->FILL($fh)
98
47bfe92f
JH
99Should return a string to be placed in the buffer. Optional. If not
100provided must provide READ or reject handles open for reading in
101PUSHED.
e7a1fdd7
NIS
102
103=item $obj->CLOSE($fh)
104
105Should return 0 on success, -1 on error.
106Optional.
107
108=item $obj->SEEK($posn,$whence,$fh)
109
110Should return 0 on success, -1 on error.
f74ea477
JH
111Optional. Default is to fail, but that is likely to be changed
112in future.
e7a1fdd7
NIS
113
114=item $obj->TELL($fh)
115
116Returns file postion.
f74ea477 117Optional. Default to be determined.
e7a1fdd7
NIS
118
119=item $obj->UNREAD($buffer,$fh)
120
47bfe92f 121Returns the number of octets from buffer that have been sucessfully
f74ea477 122saved to be returned on future FILL/READ calls. Optional. Default is
47bfe92f 123to push data into a temporary layer above this one.
e7a1fdd7
NIS
124
125=item $obj->FLUSH($fh)
126
47bfe92f
JH
127Flush any buffered write data. May possibly be called on readable
128handles too. Should return 0 on success, -1 on error.
e7a1fdd7
NIS
129
130=item $obj->SETLINEBUF($fh)
131
132Optional. No return.
133
134=item $obj->CLEARERR($fh)
135
136Optional. No return.
137
138=item $obj->ERROR($fh)
139
140Optional. Returns error state. Default is no error until a mechanism
141to signal error (die?) is worked out.
142
143=item $obj->EOF($fh)
144
47bfe92f
JH
145Optional. Returns end-of-file state. Default is function of return
146value of FILL or READ.
e7a1fdd7
NIS
147
148=back
149
a2ae6f84
JH
150=head2 Example - a Hexadecimal Handle
151
152Given the following module, Hex.pm:
153
154 package Hex;
155
156 sub PUSHED
157 {
f74ea477 158 my ($class,$mode,$fh) = @_;
a2ae6f84 159 # When writing we buffer the data
f74ea477
JH
160 my $buf = '';
161 return bless \$buf,$class;
a2ae6f84
JH
162 }
163
164 sub FILL
165 {
166 my ($obj,$fh) = @_;
167 my $line = <$fh>;
168 return (defined $line) ? pack("H*", $line) : undef;
a2ae6f84
JH
169 }
170
171 sub WRITE
172 {
173 my ($obj,$buf,$fh) = @_;
174 $$obj .= unpack("H*", $buf);
175 return length($buf);
176 }
177
178 sub FLUSH
179 {
180 my ($obj,$fh) = @_;
181 print $fh $$obj or return -1;
182 $$obj = '';
183 return 0;
184 }
185
186 1;
187
188the following code opens up an output handle that will convert any
189output to hexadecimal dump of the output bytes: for example "A" will
190be converted to "41" (on ASCII-based machines, on EBCDIC platforms
191the "A" will become "c1")
192
193 use Hex;
194 open(my $fh, ">:Via(Hex)", "foo.hex");
195
196and the following code will read the hexdump in and convert it
197on the fly back into bytes:
198
199 open(my $fh, "<:Via(Hex)", "foo.hex");
200
e7a1fdd7
NIS
201=cut
202
203
30ef3321
NIS
204
205