Commit | Line | Data |
---|---|---|
e934609f | 1 | package PerlIO::via; |
d3d34884 | 2 | our $VERSION = '0.09'; |
e7a1fdd7 | 3 | use XSLoader (); |
e934609f | 4 | XSLoader::load 'PerlIO::via'; |
e7a1fdd7 NIS |
5 | 1; |
6 | __END__ | |
7 | ||
8 | =head1 NAME | |
9 | ||
e934609f | 10 | PerlIO::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 | 22 | The PerlIO::via module allows you to develop PerlIO layers in Perl, without |
b31b80f9 EM |
23 | having to go into the nitty gritty of programming C with XS as the interface |
24 | to Perl. | |
52f3c1af | 25 | |
385e1f9f | 26 | One example module, L<PerlIO::via::QuotedPrint>, is included with Perl |
b31b80f9 | 27 | 5.8.0, and more example modules are available from CPAN, such as |
e934609f | 28 | L<PerlIO::via::StripHTML> and L<PerlIO::via::Base64>. The |
c990a0aa | 29 | PerlIO::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 | ||
35 | to obtain the text of an HTML-file in an array with all the HTML-tags | |
36 | automagically removed. | |
37 | ||
e934609f JH |
38 | Please note that if the layer is created in the PerlIO::via:: namespace, it |
39 | does B<not> have to be fully qualified. The PerlIO::via module will prefix | |
40 | the PerlIO::via:: namespace if the specified modulename does not exist as a | |
b31b80f9 | 41 | fully qualified module name. |
e7a1fdd7 | 42 | |
b31b80f9 EM |
43 | =head1 EXPECTED METHODS |
44 | ||
45 | To create a Perl module that implements a PerlIO layer in Perl (as opposed to | |
46 | in C using XS as the interface to Perl), you need to supply some of the | |
47 | following subroutines. It is recommended to create these Perl modules in the | |
e934609f JH |
48 | PerlIO::via:: namespace, so that they can easily be located on CPAN and use |
49 | the default namespace feature of the PerlIO::via module itself. | |
b31b80f9 EM |
50 | |
51 | Please note that this is an area of recent development in Perl and that the | |
c990a0aa RGS |
52 | interface described here is therefore still subject to change (and hopefully |
53 | will have better documentation and more examples). | |
b31b80f9 EM |
54 | |
55 | In the method descriptions below I<$fh> will be | |
e7a1fdd7 NIS |
56 | a reference to a glob which can be treated as a perl file handle. |
57 | It refers to the layer below. I<$fh> is not passed if the layer | |
58 | is at the bottom of the stack, for this reason and to maintain | |
2b8740d8 | 59 | some level of "compatibility" with TIEHANDLE classes it is passed last. |
802588c3 | 60 | |
e7a1fdd7 NIS |
61 | =over 4 |
62 | ||
9ec269cb | 63 | =item $class->PUSHED([$mode,[$fh]]) |
e7a1fdd7 | 64 | |
7d61c391 JH |
65 | Should return an object or the class, or -1 on failure. (Compare |
66 | TIEHANDLE.) The arguments are an optional mode string ("r", "w", | |
67 | "w+", ...) and a filehandle for the PerlIO layer below. Mandatory. | |
e7a1fdd7 | 68 | |
9ec269cb SL |
69 | When the layer is pushed as part of an C<open> call, C<PUSHED> will be called |
70 | I<before> the actual open occurs, whether that be via C<OPEN>, C<SYSOPEN>, | |
71 | C<FDOPEN> or by letting a lower layer do the open. | |
30ef3321 | 72 | |
e7a1fdd7 NIS |
73 | =item $obj->POPPED([$fh]) |
74 | ||
9ec269cb | 75 | Optional - called when the layer is about to be removed. |
e7a1fdd7 | 76 | |
802588c3 NIS |
77 | =item $obj->UTF8($bellowFlag,[$fh]) |
78 | ||
79 | Optional - if present it will be called immediately after PUSHED has | |
9ec269cb SL |
80 | returned. It should return a true value if the layer expects data to be |
81 | UTF-8 encoded. If it returns true, the result is as if the caller had done | |
802588c3 NIS |
82 | |
83 | ":via(YourClass):utf8" | |
84 | ||
9ec269cb SL |
85 | If not present or if it returns false, then the stream is left with |
86 | the UTF-8 flag clear. | |
802588c3 NIS |
87 | The I<$bellowFlag> argument will be true if there is a layer below |
88 | and that layer was expecting UTF-8. | |
89 | ||
9ec269cb | 90 | =item $obj->OPEN($path,$mode,[$fh]) |
802588c3 | 91 | |
9ec269cb SL |
92 | Optional - if not present a lower layer does the open. |
93 | If present, called for normal opens after the layer is pushed. | |
802588c3 | 94 | This function is subject to change as there is no easy way |
9ec269cb | 95 | to get a lower layer to do the open and then regain control. |
e7a1fdd7 | 96 | |
9ec269cb | 97 | =item $obj->BINMODE([$fh]) |
86e05cf2 | 98 | |
9ec269cb SL |
99 | Optional - if not present the layer is popped on binmode($fh) or when C<:raw> |
100 | is pushed. If present it should return 0 on success, -1 on error, or undef | |
86e05cf2 NIS |
101 | to pop the layer. |
102 | ||
9ec269cb | 103 | =item $obj->FDOPEN($fd,[$fh]) |
e7a1fdd7 | 104 | |
9ec269cb SL |
105 | Optional - if not present a lower layer does the open. |
106 | If present, called after the layer is pushed for opens which pass | |
107 | a numeric file descriptor. | |
802588c3 | 108 | This function is subject to change as there is no easy way |
9ec269cb | 109 | to get a lower layer to do the open and then regain control. |
e7a1fdd7 | 110 | |
9ec269cb | 111 | =item $obj->SYSOPEN($path,$imode,$perm,[$fh]) |
e7a1fdd7 | 112 | |
9ec269cb SL |
113 | Optional - if not present a lower layer does the open. |
114 | If present, called after the layer is pushed for sysopen style opens | |
115 | which pass a numeric mode and permissions. | |
802588c3 | 116 | This function is subject to change as there is no easy way |
9ec269cb | 117 | to get a lower layer to do the open and then regain control. |
e7a1fdd7 NIS |
118 | |
119 | =item $obj->FILENO($fh) | |
120 | ||
9ec269cb | 121 | Returns a numeric value for a Unix-like file descriptor. Returns -1 if |
47bfe92f | 122 | there isn't one. Optional. Default is fileno($fh). |
e7a1fdd7 NIS |
123 | |
124 | =item $obj->READ($buffer,$len,$fh) | |
125 | ||
6391fff2 MJD |
126 | Returns the number of octets placed in $buffer (must be less than or |
127 | equal to $len). Optional. Default is to use FILL instead. | |
e7a1fdd7 NIS |
128 | |
129 | =item $obj->WRITE($buffer,$fh) | |
130 | ||
9ec269cb | 131 | Returns the number of octets from $buffer that have been successfully written. |
e7a1fdd7 NIS |
132 | |
133 | =item $obj->FILL($fh) | |
134 | ||
47bfe92f | 135 | Should return a string to be placed in the buffer. Optional. If not |
9ec269cb | 136 | provided, must provide READ or reject handles open for reading in |
47bfe92f | 137 | PUSHED. |
e7a1fdd7 NIS |
138 | |
139 | =item $obj->CLOSE($fh) | |
140 | ||
141 | Should return 0 on success, -1 on error. | |
142 | Optional. | |
143 | ||
144 | =item $obj->SEEK($posn,$whence,$fh) | |
145 | ||
146 | Should return 0 on success, -1 on error. | |
f74ea477 JH |
147 | Optional. Default is to fail, but that is likely to be changed |
148 | in future. | |
e7a1fdd7 NIS |
149 | |
150 | =item $obj->TELL($fh) | |
151 | ||
055cc54b | 152 | Returns file position. |
f74ea477 | 153 | Optional. Default to be determined. |
e7a1fdd7 NIS |
154 | |
155 | =item $obj->UNREAD($buffer,$fh) | |
156 | ||
9ec269cb | 157 | Returns the number of octets from $buffer that have been successfully |
f74ea477 | 158 | saved to be returned on future FILL/READ calls. Optional. Default is |
47bfe92f | 159 | to push data into a temporary layer above this one. |
e7a1fdd7 NIS |
160 | |
161 | =item $obj->FLUSH($fh) | |
162 | ||
47bfe92f JH |
163 | Flush any buffered write data. May possibly be called on readable |
164 | handles too. Should return 0 on success, -1 on error. | |
e7a1fdd7 NIS |
165 | |
166 | =item $obj->SETLINEBUF($fh) | |
167 | ||
168 | Optional. No return. | |
169 | ||
170 | =item $obj->CLEARERR($fh) | |
171 | ||
172 | Optional. No return. | |
173 | ||
174 | =item $obj->ERROR($fh) | |
175 | ||
176 | Optional. Returns error state. Default is no error until a mechanism | |
177 | to signal error (die?) is worked out. | |
178 | ||
179 | =item $obj->EOF($fh) | |
180 | ||
9ec269cb | 181 | Optional. Returns end-of-file state. Default is a function of the return |
47bfe92f | 182 | value of FILL or READ. |
e7a1fdd7 NIS |
183 | |
184 | =back | |
185 | ||
b31b80f9 EM |
186 | =head1 EXAMPLES |
187 | ||
e934609f | 188 | Check the PerlIO::via:: namespace on CPAN for examples of PerlIO layers |
b31b80f9 | 189 | implemented in Perl. To give you an idea how simple the implementation of |
9ec269cb | 190 | a PerlIO layer can look, a simple example is included here. |
b31b80f9 | 191 | |
a2ae6f84 JH |
192 | =head2 Example - a Hexadecimal Handle |
193 | ||
c990a0aa | 194 | Given the following module, PerlIO::via::Hex : |
a2ae6f84 | 195 | |
e934609f | 196 | package PerlIO::via::Hex; |
a2ae6f84 JH |
197 | |
198 | sub PUSHED | |
199 | { | |
f74ea477 | 200 | my ($class,$mode,$fh) = @_; |
a2ae6f84 | 201 | # When writing we buffer the data |
f74ea477 JH |
202 | my $buf = ''; |
203 | return bless \$buf,$class; | |
a2ae6f84 JH |
204 | } |
205 | ||
206 | sub FILL | |
207 | { | |
208 | my ($obj,$fh) = @_; | |
209 | my $line = <$fh>; | |
210 | return (defined $line) ? pack("H*", $line) : undef; | |
a2ae6f84 JH |
211 | } |
212 | ||
213 | sub WRITE | |
214 | { | |
215 | my ($obj,$buf,$fh) = @_; | |
216 | $$obj .= unpack("H*", $buf); | |
217 | return length($buf); | |
218 | } | |
219 | ||
220 | sub FLUSH | |
221 | { | |
222 | my ($obj,$fh) = @_; | |
223 | print $fh $$obj or return -1; | |
224 | $$obj = ''; | |
225 | return 0; | |
226 | } | |
227 | ||
228 | 1; | |
229 | ||
055cc54b | 230 | The following code opens up an output handle that will convert any |
9ec269cb | 231 | output to a hexadecimal dump of the output bytes: for example "A" will |
a2ae6f84 JH |
232 | be converted to "41" (on ASCII-based machines, on EBCDIC platforms |
233 | the "A" will become "c1") | |
234 | ||
e934609f JH |
235 | use PerlIO::via::Hex; |
236 | open(my $fh, ">:via(Hex)", "foo.hex"); | |
a2ae6f84 JH |
237 | |
238 | and the following code will read the hexdump in and convert it | |
239 | on the fly back into bytes: | |
240 | ||
e934609f | 241 | open(my $fh, "<:via(Hex)", "foo.hex"); |
a2ae6f84 | 242 | |
e7a1fdd7 | 243 | =cut |