Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | package PerlIO; |
2 | ||
3 | our $VERSION = '1.01'; | |
4 | ||
5 | # Map layer name to package that defines it | |
6 | our %alias; | |
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 | ||
27 | 1; | |
28 | __END__ | |
29 | ||
30 | =head1 NAME | |
31 | ||
32 | PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space | |
33 | ||
34 | =head1 SYNOPSIS | |
35 | ||
36 | open($fh,"<:crlf", "my.txt"); # portably open a text file for reading | |
37 | ||
38 | open($fh,"<","his.jpg"); # portably open a binary file for reading | |
39 | binmode($fh); | |
40 | ||
41 | Shell: | |
42 | PERLIO=perlio perl .... | |
43 | ||
44 | =head1 DESCRIPTION | |
45 | ||
46 | When an undefined layer 'foo' is encountered in an C<open> or | |
47 | C<binmode> layer specification then C code performs the equivalent of: | |
48 | ||
49 | use PerlIO 'foo'; | |
50 | ||
51 | The perl code in PerlIO.pm then attempts to locate a layer by doing | |
52 | ||
53 | require PerlIO::foo; | |
54 | ||
55 | Otherwise the C<PerlIO> package is a place holder for additional | |
56 | PerlIO related functions. | |
57 | ||
58 | The following layers are currently defined: | |
59 | ||
60 | =over 4 | |
61 | ||
62 | =item unix | |
63 | ||
64 | Low level layer which calls C<read>, C<write> and C<lseek> etc. | |
65 | ||
66 | =item stdio | |
67 | ||
68 | Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc. Note | |
69 | that as this is "real" stdio it will ignore any layers beneath it and | |
70 | got straight to the operating system via the C library as usual. | |
71 | ||
72 | =item perlio | |
73 | ||
74 | This is a re-implementation of "stdio-like" buffering written as a | |
75 | PerlIO "layer". As such it will call whatever layer is below it for | |
76 | its operations. | |
77 | ||
78 | =item crlf | |
79 | ||
80 | A layer which does CRLF to "\n" translation distinguishing "text" and | |
81 | "binary" files in the manner of MS-DOS and similar operating systems. | |
82 | (It currently does I<not> mimic MS-DOS as far as treating of Control-Z | |
83 | as being an end-of-file marker.) | |
84 | ||
85 | =item utf8 | |
86 | ||
87 | Declares that the stream accepts perl's internal encoding of | |
88 | characters. (Which really is UTF-8 on ASCII machines, but is | |
89 | UTF-EBCDIC on EBCDIC machines.) This allows any character perl can | |
90 | represent to be read from or written to the stream. The UTF-X encoding | |
91 | is chosen to render simple text parts (i.e. non-accented letters, | |
92 | digits and common punctuation) human readable in the encoded file. | |
93 | ||
94 | Here is how to write your native data out using UTF-8 (or UTF-EBCDIC) | |
95 | and then read it back in. | |
96 | ||
97 | open(F, ">:utf8", "data.utf"); | |
98 | print F $out; | |
99 | close(F); | |
100 | ||
101 | open(F, "<:utf8", "data.utf"); | |
102 | $in = <F>; | |
103 | close(F); | |
104 | ||
105 | =item bytes | |
106 | ||
107 | This is the inverse of C<:utf8> layer. It turns off the flag | |
108 | on the layer below so that data read from it is considered to | |
109 | be "octets" i.e. characters in range 0..255 only. Likewise | |
110 | on output perl will warn if a "wide" character is written | |
111 | to a such a stream. | |
112 | ||
113 | =item raw | |
114 | ||
115 | The C<:raw> layer is I<defined> as being identical to calling | |
116 | C<binmode($fh)> - the stream is made suitable for passing binary | |
117 | data i.e. each byte is passed as-is. The stream will still be | |
118 | buffered. Unlike earlier versions of perl C<:raw> is I<not> just the | |
119 | inverse of C<:crlf> - other layers which would affect the binary nature of | |
120 | the stream are also removed or disabled. | |
121 | ||
122 | The implementation of C<:raw> is as a pseudo-layer which when "pushed" | |
123 | pops itself and then any layers which do not declare themselves as suitable | |
124 | for binary data. (Undoing :utf8 and :crlf are implemented by clearing | |
125 | flags rather than poping layers but that is an implementation detail.) | |
126 | ||
127 | As a consequence of the fact that C<:raw> normally pops layers | |
128 | it usually only makes sense to have it as the only or first element in a | |
129 | layer specification. When used as the first element it provides | |
130 | a known base on which to build e.g. | |
131 | ||
132 | open($fh,":raw:utf8",...) | |
133 | ||
134 | will construct a "binary" stream, but then enable UTF-8 translation. | |
135 | ||
136 | =item pop | |
137 | ||
138 | A pseudo layer that removes the top-most layer. Gives perl code | |
139 | a way to manipulate the layer stack. Should be considered | |
140 | as experimental. Note that C<:pop> only works on real layers | |
141 | and will not undo the effects of pseudo layers like C<:utf8>. | |
142 | An example of a possible use might be: | |
143 | ||
144 | open($fh,...) | |
145 | ... | |
146 | binmode($fh,":encoding(...)"); # next chunk is encoded | |
147 | ... | |
148 | binmode($fh,":pop"); # back to un-encocded | |
149 | ||
150 | A more elegant (and safer) interface is needed. | |
151 | ||
152 | =back | |
153 | ||
154 | =head2 Alternatives to raw | |
155 | ||
156 | To get a binary stream an alternate method is to use: | |
157 | ||
158 | open($fh,"whatever") | |
159 | binmode($fh); | |
160 | ||
161 | this has advantage of being backward compatible with how such things have | |
162 | had to be coded on some platforms for years. | |
163 | ||
164 | To get an un-buffered stream specify an unbuffered layer (e.g. C<:unix>) | |
165 | in the open call: | |
166 | ||
167 | open($fh,"<:unix",$path) | |
168 | ||
169 | =head2 Defaults and how to override them | |
170 | ||
171 | If the platform is MS-DOS like and normally does CRLF to "\n" | |
172 | translation for text files then the default layers are : | |
173 | ||
174 | unix crlf | |
175 | ||
176 | (The low level "unix" layer may be replaced by a platform specific low | |
177 | level layer.) | |
178 | ||
179 | Otherwise if C<Configure> found out how to do "fast" IO using system's | |
180 | stdio, then the default layers are : | |
181 | ||
182 | unix stdio | |
183 | ||
184 | Otherwise the default layers are | |
185 | ||
186 | unix perlio | |
187 | ||
188 | These defaults may change once perlio has been better tested and tuned. | |
189 | ||
190 | The default can be overridden by setting the environment variable | |
191 | PERLIO to a space separated list of layers (unix or platform low level | |
192 | layer is always pushed first). | |
193 | ||
194 | This can be used to see the effect of/bugs in the various layers e.g. | |
195 | ||
196 | cd .../perl/t | |
197 | PERLIO=stdio ./perl harness | |
198 | PERLIO=perlio ./perl harness | |
199 | ||
200 | =head1 AUTHOR | |
201 | ||
202 | Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt> | |
203 | ||
204 | =head1 SEE ALSO | |
205 | ||
206 | L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<Encode> | |
207 | ||
208 | =cut | |
209 |