Commit | Line | Data |
---|---|---|
1141d9f8 NIS |
1 | package PerlIO; |
2 | ||
92a3e63c | 3 | our $VERSION = '1.02'; |
8de1277c | 4 | |
1141d9f8 | 5 | # Map layer name to package that defines it |
c1a61b17 | 6 | our %alias; |
1141d9f8 NIS |
7 | |
8 | sub import | |
9 | { | |
10 | my $class = shift; | |
11 | while (@_) | |
12 | { | |
13 | my $layer = shift; | |
14 | if (exists $alias{$layer}) | |
15 | { | |
16 | $layer = $alias{$layer} | |
17 | } | |
18 | else | |
19 | { | |
20 | $layer = "${class}::$layer"; | |
21 | } | |
22 | eval "require $layer"; | |
23 | warn $@ if $@; | |
24 | } | |
25 | } | |
26 | ||
39f7a870 JH |
27 | sub F_UTF8 () { 0x8000 } |
28 | ||
1141d9f8 NIS |
29 | 1; |
30 | __END__ | |
b3d30bf7 NIS |
31 | |
32 | =head1 NAME | |
33 | ||
7d3b96bb | 34 | PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space |
b3d30bf7 NIS |
35 | |
36 | =head1 SYNOPSIS | |
37 | ||
01e6739c | 38 | open($fh,"<:crlf", "my.txt"); # portably open a text file for reading |
1cbfc93d NIS |
39 | |
40 | open($fh,"<","his.jpg"); # portably open a binary file for reading | |
41 | binmode($fh); | |
7d3b96bb NIS |
42 | |
43 | Shell: | |
44 | PERLIO=perlio perl .... | |
b3d30bf7 NIS |
45 | |
46 | =head1 DESCRIPTION | |
47 | ||
ec28694c JH |
48 | When an undefined layer 'foo' is encountered in an C<open> or |
49 | C<binmode> layer specification then C code performs the equivalent of: | |
b3d30bf7 NIS |
50 | |
51 | use PerlIO 'foo'; | |
52 | ||
53 | The perl code in PerlIO.pm then attempts to locate a layer by doing | |
54 | ||
55 | require PerlIO::foo; | |
56 | ||
47bfe92f JH |
57 | Otherwise the C<PerlIO> package is a place holder for additional |
58 | PerlIO related functions. | |
b3d30bf7 | 59 | |
7d3b96bb | 60 | The following layers are currently defined: |
b3d30bf7 | 61 | |
7d3b96bb NIS |
62 | =over 4 |
63 | ||
64 | =item unix | |
65 | ||
66 | Low level layer which calls C<read>, C<write> and C<lseek> etc. | |
67 | ||
68 | =item stdio | |
69 | ||
47bfe92f JH |
70 | Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc. Note |
71 | that as this is "real" stdio it will ignore any layers beneath it and | |
7d3b96bb NIS |
72 | got straight to the operating system via the C library as usual. |
73 | ||
74 | =item perlio | |
75 | ||
47bfe92f JH |
76 | This is a re-implementation of "stdio-like" buffering written as a |
77 | PerlIO "layer". As such it will call whatever layer is below it for | |
78 | its operations. | |
7d3b96bb NIS |
79 | |
80 | =item crlf | |
81 | ||
47bfe92f JH |
82 | A layer which does CRLF to "\n" translation distinguishing "text" and |
83 | "binary" files in the manner of MS-DOS and similar operating systems. | |
0226bbdb NIS |
84 | (It currently does I<not> mimic MS-DOS as far as treating of Control-Z |
85 | as being an end-of-file marker.) | |
7d3b96bb NIS |
86 | |
87 | =item utf8 | |
88 | ||
47bfe92f JH |
89 | Declares that the stream accepts perl's internal encoding of |
90 | characters. (Which really is UTF-8 on ASCII machines, but is | |
91 | UTF-EBCDIC on EBCDIC machines.) This allows any character perl can | |
92 | represent to be read from or written to the stream. The UTF-X encoding | |
93 | is chosen to render simple text parts (i.e. non-accented letters, | |
94 | digits and common punctuation) human readable in the encoded file. | |
95 | ||
96 | Here is how to write your native data out using UTF-8 (or UTF-EBCDIC) | |
97 | and then read it back in. | |
98 | ||
99 | open(F, ">:utf8", "data.utf"); | |
100 | print F $out; | |
101 | close(F); | |
102 | ||
103 | open(F, "<:utf8", "data.utf"); | |
104 | $in = <F>; | |
105 | close(F); | |
7d3b96bb | 106 | |
c1a61b17 NIS |
107 | =item bytes |
108 | ||
109 | This is the inverse of C<:utf8> layer. It turns off the flag | |
110 | on the layer below so that data read from it is considered to | |
111 | be "octets" i.e. characters in range 0..255 only. Likewise | |
112 | on output perl will warn if a "wide" character is written | |
113 | to a such a stream. | |
114 | ||
7d3b96bb NIS |
115 | =item raw |
116 | ||
0226bbdb NIS |
117 | The C<:raw> layer is I<defined> as being identical to calling |
118 | C<binmode($fh)> - the stream is made suitable for passing binary | |
119 | data i.e. each byte is passed as-is. The stream will still be | |
120 | buffered. Unlike earlier versions of perl C<:raw> is I<not> just the | |
121 | inverse of C<:crlf> - other layers which would affect the binary nature of | |
122 | the stream are also removed or disabled. | |
1cbfc93d | 123 | |
0226bbdb NIS |
124 | The implementation of C<:raw> is as a pseudo-layer which when "pushed" |
125 | pops itself and then any layers which do not declare themselves as suitable | |
126 | for binary data. (Undoing :utf8 and :crlf are implemented by clearing | |
39f7a870 | 127 | flags rather than popping layers but that is an implementation detail.) |
01e6739c | 128 | |
0226bbdb | 129 | As a consequence of the fact that C<:raw> normally pops layers |
39f7a870 JH |
130 | it usually only makes sense to have it as the only or first element in |
131 | a layer specification. When used as the first element it provides | |
0226bbdb | 132 | a known base on which to build e.g. |
7d3b96bb | 133 | |
0226bbdb | 134 | open($fh,":raw:utf8",...) |
7d3b96bb | 135 | |
0226bbdb | 136 | will construct a "binary" stream, but then enable UTF-8 translation. |
b3d30bf7 | 137 | |
4ec2216f NIS |
138 | =item pop |
139 | ||
140 | A pseudo layer that removes the top-most layer. Gives perl code | |
141 | a way to manipulate the layer stack. Should be considered | |
142 | as experimental. Note that C<:pop> only works on real layers | |
143 | and will not undo the effects of pseudo layers like C<:utf8>. | |
144 | An example of a possible use might be: | |
145 | ||
146 | open($fh,...) | |
147 | ... | |
148 | binmode($fh,":encoding(...)"); # next chunk is encoded | |
149 | ... | |
150 | binmode($fh,":pop"); # back to un-encocded | |
151 | ||
152 | A more elegant (and safer) interface is needed. | |
153 | ||
7d3b96bb NIS |
154 | =back |
155 | ||
39f7a870 JH |
156 | =head2 Custom Layers |
157 | ||
158 | It is possible to write custom layers in addition to the above builtin | |
159 | ones, both in C/XS and Perl. Two such layers (and one example written | |
160 | in Perl using the latter) come with the Perl distribution. | |
161 | ||
162 | =over 4 | |
163 | ||
164 | =item :encoding | |
165 | ||
166 | Use C<:encoding(ENCODING)> either in open() or binmode() to install | |
167 | a layer that does transparently character set and encoding transformations, | |
168 | for example from Shift-JIS to Unicode. Note that an C<:encoding> also | |
169 | enables C<:utf8>. See L<PerlIO::encoding> for more information. | |
170 | ||
171 | =item :via | |
172 | ||
173 | Use C<:via(MODULE)> either in open() or binmode() to install a layer | |
174 | that does whatever transformation (for example compression / | |
175 | decompression, encryption / decryption) to the filehandle. | |
176 | See L<PerlIO::via> for more information. | |
177 | ||
178 | =back | |
179 | ||
01e6739c NIS |
180 | =head2 Alternatives to raw |
181 | ||
0226bbdb | 182 | To get a binary stream an alternate method is to use: |
01e6739c | 183 | |
0226bbdb | 184 | open($fh,"whatever") |
01e6739c NIS |
185 | binmode($fh); |
186 | ||
0226bbdb | 187 | this has advantage of being backward compatible with how such things have |
01e6739c | 188 | had to be coded on some platforms for years. |
01e6739c NIS |
189 | |
190 | To get an un-buffered stream specify an unbuffered layer (e.g. C<:unix>) | |
0226bbdb | 191 | in the open call: |
01e6739c NIS |
192 | |
193 | open($fh,"<:unix",$path) | |
194 | ||
7d3b96bb NIS |
195 | =head2 Defaults and how to override them |
196 | ||
ec28694c JH |
197 | If the platform is MS-DOS like and normally does CRLF to "\n" |
198 | translation for text files then the default layers are : | |
7d3b96bb NIS |
199 | |
200 | unix crlf | |
201 | ||
47bfe92f JH |
202 | (The low level "unix" layer may be replaced by a platform specific low |
203 | level layer.) | |
7d3b96bb | 204 | |
47bfe92f JH |
205 | Otherwise if C<Configure> found out how to do "fast" IO using system's |
206 | stdio, then the default layers are : | |
7d3b96bb NIS |
207 | |
208 | unix stdio | |
209 | ||
210 | Otherwise the default layers are | |
211 | ||
212 | unix perlio | |
213 | ||
214 | These defaults may change once perlio has been better tested and tuned. | |
215 | ||
47bfe92f | 216 | The default can be overridden by setting the environment variable |
39f7a870 JH |
217 | PERLIO to a space separated list of layers (C<unix> or platform low |
218 | level layer is always pushed first). | |
47bfe92f | 219 | |
7d3b96bb NIS |
220 | This can be used to see the effect of/bugs in the various layers e.g. |
221 | ||
222 | cd .../perl/t | |
223 | PERLIO=stdio ./perl harness | |
224 | PERLIO=perlio ./perl harness | |
225 | ||
39f7a870 JH |
226 | =head2 Querying the layers of filehandle |
227 | ||
228 | The following returns the B<names> of the PerlIO layers on a filehandle. | |
229 | ||
230 | my @layers = PerlIO::get_layers(FH); | |
231 | ||
232 | The layers are returned in the order an open() or binmode() call would | |
233 | use them. Note that the stack begings (normally) from C<stdio>, the | |
234 | platform specific low-level I/O (like C<unix>) is not part of the stack. | |
235 | ||
236 | By default the layers from the input side of the filehandle is | |
237 | returned, to get the output side use the optional C<output> argument: | |
238 | ||
239 | my @layers = PerlIO::get_layers(FH, output => 1); | |
240 | ||
241 | (Usually the layers are identical on either side of a filehandle but | |
242 | for example with sockets there may be differences.) | |
243 | ||
92a3e63c JH |
244 | There is no set_layers(), nor does get_layers() return a tied array |
245 | mirroring the stack, or anything fancy like that. This is not | |
246 | accidental or unintentional. The PerlIO layer stack is a bit more | |
247 | complicated than just a stack (see for example the behaviour of C<:raw>). | |
248 | You are supposed to use open() and binmode() to manipulate the stack. | |
249 | ||
39f7a870 JH |
250 | B<Implementation details follow, please close your eyes.> |
251 | ||
252 | The arguments to layers are by default returned in parenthesis after | |
253 | the name of the layer, and certain layers (like C<utf8>) are not real | |
254 | layers but instead flags on real layers: to get all of these returned | |
255 | separately use the optional C<separate> argument: | |
256 | ||
257 | my @layer_and_args_and_flags = PerlIO::get_layers(FH, details => 1); | |
258 | ||
259 | The result will be up to be three times the number of layers: | |
260 | the first element will be a name, the second element the arguments | |
261 | (unspecified arguments will be C<undef>), the third element the flags, | |
262 | the fourth element a name again, and so forth. | |
263 | ||
264 | B<You may open your eyes now.> | |
265 | ||
7d3b96bb NIS |
266 | =head1 AUTHOR |
267 | ||
268 | Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt> | |
269 | ||
270 | =head1 SEE ALSO | |
271 | ||
39f7a870 JH |
272 | L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<perliol>, |
273 | L<Encode> | |
7d3b96bb NIS |
274 | |
275 | =cut | |
b3d30bf7 | 276 |