Commit | Line | Data |
---|---|---|
1141d9f8 NIS |
1 | package PerlIO; |
2 | ||
3 | # Map layer name to package that defines it | |
4 | my %alias = (encoding => 'Encode'); | |
5 | ||
6 | sub import | |
7 | { | |
8 | my $class = shift; | |
9 | while (@_) | |
10 | { | |
11 | my $layer = shift; | |
12 | if (exists $alias{$layer}) | |
13 | { | |
14 | $layer = $alias{$layer} | |
15 | } | |
16 | else | |
17 | { | |
18 | $layer = "${class}::$layer"; | |
19 | } | |
20 | eval "require $layer"; | |
21 | warn $@ if $@; | |
22 | } | |
23 | } | |
24 | ||
25 | 1; | |
26 | __END__ | |
b3d30bf7 NIS |
27 | |
28 | =head1 NAME | |
29 | ||
7d3b96bb | 30 | PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space |
b3d30bf7 NIS |
31 | |
32 | =head1 SYNOPSIS | |
33 | ||
7d3b96bb NIS |
34 | open($fh,">:crlf","my.txt") |
35 | open($fh,">:raw","his.jpg") | |
36 | ||
37 | Shell: | |
38 | PERLIO=perlio perl .... | |
b3d30bf7 NIS |
39 | |
40 | =head1 DESCRIPTION | |
41 | ||
ec28694c JH |
42 | When an undefined layer 'foo' is encountered in an C<open> or |
43 | C<binmode> layer specification then C code performs the equivalent of: | |
b3d30bf7 NIS |
44 | |
45 | use PerlIO 'foo'; | |
46 | ||
47 | The perl code in PerlIO.pm then attempts to locate a layer by doing | |
48 | ||
49 | require PerlIO::foo; | |
50 | ||
47bfe92f JH |
51 | Otherwise the C<PerlIO> package is a place holder for additional |
52 | PerlIO related functions. | |
b3d30bf7 | 53 | |
7d3b96bb | 54 | The following layers are currently defined: |
b3d30bf7 | 55 | |
7d3b96bb NIS |
56 | =over 4 |
57 | ||
58 | =item unix | |
59 | ||
60 | Low level layer which calls C<read>, C<write> and C<lseek> etc. | |
61 | ||
62 | =item stdio | |
63 | ||
47bfe92f JH |
64 | Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc. Note |
65 | that as this is "real" stdio it will ignore any layers beneath it and | |
7d3b96bb NIS |
66 | got straight to the operating system via the C library as usual. |
67 | ||
68 | =item perlio | |
69 | ||
47bfe92f JH |
70 | This is a re-implementation of "stdio-like" buffering written as a |
71 | PerlIO "layer". As such it will call whatever layer is below it for | |
72 | its operations. | |
7d3b96bb NIS |
73 | |
74 | =item crlf | |
75 | ||
47bfe92f JH |
76 | A layer which does CRLF to "\n" translation distinguishing "text" and |
77 | "binary" files in the manner of MS-DOS and similar operating systems. | |
7d3b96bb NIS |
78 | |
79 | =item utf8 | |
80 | ||
47bfe92f JH |
81 | Declares that the stream accepts perl's internal encoding of |
82 | characters. (Which really is UTF-8 on ASCII machines, but is | |
83 | UTF-EBCDIC on EBCDIC machines.) This allows any character perl can | |
84 | represent to be read from or written to the stream. The UTF-X encoding | |
85 | is chosen to render simple text parts (i.e. non-accented letters, | |
86 | digits and common punctuation) human readable in the encoded file. | |
87 | ||
88 | Here is how to write your native data out using UTF-8 (or UTF-EBCDIC) | |
89 | and then read it back in. | |
90 | ||
91 | open(F, ">:utf8", "data.utf"); | |
92 | print F $out; | |
93 | close(F); | |
94 | ||
95 | open(F, "<:utf8", "data.utf"); | |
96 | $in = <F>; | |
97 | close(F); | |
7d3b96bb NIS |
98 | |
99 | =item raw | |
100 | ||
47bfe92f | 101 | A pseudo-layer which performs two functions (which is messy, but |
ec28694c | 102 | necessary to maintain compatibility with non-PerlIO builds of Perl |
47bfe92f | 103 | and their way things have been documented elsewhere). |
7d3b96bb | 104 | |
47bfe92f JH |
105 | Firstly it forces the file handle to be considered binary at that |
106 | point in the layer stack, | |
7d3b96bb | 107 | |
47bfe92f JH |
108 | Secondly in prevents the IO system seaching back before it in the |
109 | layer specification. Thus: | |
7d3b96bb | 110 | |
47bfe92f | 111 | open($fh,":raw:perlio",...) |
7d3b96bb | 112 | |
47bfe92f JH |
113 | Forces the use of C<perlio> layer even if the platform default, or |
114 | C<use open> default is something else (such as ":encoding(iso-8859-7)") | |
42234700 JH |
115 | (the C<:encoding> requires C<use Encode>) which would interfere with |
116 | binary nature of the stream. | |
b3d30bf7 | 117 | |
7d3b96bb NIS |
118 | =back |
119 | ||
120 | =head2 Defaults and how to override them | |
121 | ||
ec28694c JH |
122 | If the platform is MS-DOS like and normally does CRLF to "\n" |
123 | translation for text files then the default layers are : | |
7d3b96bb NIS |
124 | |
125 | unix crlf | |
126 | ||
47bfe92f JH |
127 | (The low level "unix" layer may be replaced by a platform specific low |
128 | level layer.) | |
7d3b96bb | 129 | |
47bfe92f JH |
130 | Otherwise if C<Configure> found out how to do "fast" IO using system's |
131 | stdio, then the default layers are : | |
7d3b96bb NIS |
132 | |
133 | unix stdio | |
134 | ||
135 | Otherwise the default layers are | |
136 | ||
137 | unix perlio | |
138 | ||
139 | These defaults may change once perlio has been better tested and tuned. | |
140 | ||
47bfe92f JH |
141 | The default can be overridden by setting the environment variable |
142 | PERLIO to a space separated list of layers (unix or platform low level | |
143 | layer is always pushed first). | |
144 | ||
7d3b96bb NIS |
145 | This can be used to see the effect of/bugs in the various layers e.g. |
146 | ||
147 | cd .../perl/t | |
148 | PERLIO=stdio ./perl harness | |
149 | PERLIO=perlio ./perl harness | |
150 | ||
151 | =head1 AUTHOR | |
152 | ||
153 | Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt> | |
154 | ||
155 | =head1 SEE ALSO | |
156 | ||
47bfe92f | 157 | L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<Encode> |
7d3b96bb NIS |
158 | |
159 | =cut | |
b3d30bf7 | 160 |