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