This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix open(FH,"Via(Foo)","NonExistant") and other cases when
[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
NIS
45
46=item $obj->POPPED([$fh])
47
48Optional - layer is about to be removed.
49
50=item $class->OPEN($path,$mode[,$fh])
51
52Not yet in use.
53
86e05cf2
NIS
54=item $obj->BINMODE([,$fh])
55
56Optional - if not available layer is popped on binmode($fh) or when C<:raw>
57is pushed. If present it should return 0 on success -1 on error and undef
58to pop the layer.
59
e7a1fdd7
NIS
60=item $class->FDOPEN($fd)
61
62Not yet in use.
63
64=item $class->SYSOPEN($path,$imode,$perm,$fh)
65
66Not yet in use.
67
68=item $obj->FILENO($fh)
69
47bfe92f
JH
70Returns a numeric value for Unix-like file descriptor. Return -1 if
71there isn't one. Optional. Default is fileno($fh).
e7a1fdd7
NIS
72
73=item $obj->READ($buffer,$len,$fh)
74
6391fff2
MJD
75Returns the number of octets placed in $buffer (must be less than or
76equal to $len). Optional. Default is to use FILL instead.
e7a1fdd7
NIS
77
78=item $obj->WRITE($buffer,$fh)
79
80Returns the number of octets from buffer that have been sucessfully written.
81
82=item $obj->FILL($fh)
83
47bfe92f
JH
84Should return a string to be placed in the buffer. Optional. If not
85provided must provide READ or reject handles open for reading in
86PUSHED.
e7a1fdd7
NIS
87
88=item $obj->CLOSE($fh)
89
90Should return 0 on success, -1 on error.
91Optional.
92
93=item $obj->SEEK($posn,$whence,$fh)
94
95Should return 0 on success, -1 on error.
f74ea477
JH
96Optional. Default is to fail, but that is likely to be changed
97in future.
e7a1fdd7
NIS
98
99=item $obj->TELL($fh)
100
101Returns file postion.
f74ea477 102Optional. Default to be determined.
e7a1fdd7
NIS
103
104=item $obj->UNREAD($buffer,$fh)
105
47bfe92f 106Returns the number of octets from buffer that have been sucessfully
f74ea477 107saved to be returned on future FILL/READ calls. Optional. Default is
47bfe92f 108to push data into a temporary layer above this one.
e7a1fdd7
NIS
109
110=item $obj->FLUSH($fh)
111
47bfe92f
JH
112Flush any buffered write data. May possibly be called on readable
113handles too. Should return 0 on success, -1 on error.
e7a1fdd7
NIS
114
115=item $obj->SETLINEBUF($fh)
116
117Optional. No return.
118
119=item $obj->CLEARERR($fh)
120
121Optional. No return.
122
123=item $obj->ERROR($fh)
124
125Optional. Returns error state. Default is no error until a mechanism
126to signal error (die?) is worked out.
127
128=item $obj->EOF($fh)
129
47bfe92f
JH
130Optional. Returns end-of-file state. Default is function of return
131value of FILL or READ.
e7a1fdd7
NIS
132
133=back
134
a2ae6f84
JH
135=head2 Example - a Hexadecimal Handle
136
137Given the following module, Hex.pm:
138
139 package Hex;
140
141 sub PUSHED
142 {
f74ea477 143 my ($class,$mode,$fh) = @_;
a2ae6f84 144 # When writing we buffer the data
f74ea477
JH
145 my $buf = '';
146 return bless \$buf,$class;
a2ae6f84
JH
147 }
148
149 sub FILL
150 {
151 my ($obj,$fh) = @_;
152 my $line = <$fh>;
153 return (defined $line) ? pack("H*", $line) : undef;
a2ae6f84
JH
154 }
155
156 sub WRITE
157 {
158 my ($obj,$buf,$fh) = @_;
159 $$obj .= unpack("H*", $buf);
160 return length($buf);
161 }
162
163 sub FLUSH
164 {
165 my ($obj,$fh) = @_;
166 print $fh $$obj or return -1;
167 $$obj = '';
168 return 0;
169 }
170
171 1;
172
173the following code opens up an output handle that will convert any
174output to hexadecimal dump of the output bytes: for example "A" will
175be converted to "41" (on ASCII-based machines, on EBCDIC platforms
176the "A" will become "c1")
177
178 use Hex;
179 open(my $fh, ">:Via(Hex)", "foo.hex");
180
181and the following code will read the hexdump in and convert it
182on the fly back into bytes:
183
184 open(my $fh, "<:Via(Hex)", "foo.hex");
185
e7a1fdd7
NIS
186=cut
187
188