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 | ||
42 | When an undefined layer 'foo' is encountered in an C<open> or C<binmode> layer | |
43 | specification then C code performs the equivalent of: | |
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 JH |
101 | A pseudo-layer which performs two functions (which is messy, but |
102 | necessary to maintain compatibility with non-PerlIO builds of perl | |
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)") | |
115 | which would interfere with binary nature of the stream. | |
b3d30bf7 | 116 | |
7d3b96bb NIS |
117 | =back |
118 | ||
119 | =head2 Defaults and how to override them | |
120 | ||
121 | If the platform is MS-DOS like and normally does CRLF to "\n" translation | |
122 | for text files then the default layers are : | |
123 | ||
124 | unix crlf | |
125 | ||
47bfe92f JH |
126 | (The low level "unix" layer may be replaced by a platform specific low |
127 | level layer.) | |
7d3b96bb | 128 | |
47bfe92f JH |
129 | Otherwise if C<Configure> found out how to do "fast" IO using system's |
130 | stdio, then the default layers are : | |
7d3b96bb NIS |
131 | |
132 | unix stdio | |
133 | ||
134 | Otherwise the default layers are | |
135 | ||
136 | unix perlio | |
137 | ||
138 | These defaults may change once perlio has been better tested and tuned. | |
139 | ||
47bfe92f JH |
140 | The default can be overridden by setting the environment variable |
141 | PERLIO to a space separated list of layers (unix or platform low level | |
142 | layer is always pushed first). | |
143 | ||
7d3b96bb NIS |
144 | This can be used to see the effect of/bugs in the various layers e.g. |
145 | ||
146 | cd .../perl/t | |
147 | PERLIO=stdio ./perl harness | |
148 | PERLIO=perlio ./perl harness | |
149 | ||
150 | =head1 AUTHOR | |
151 | ||
152 | Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt> | |
153 | ||
154 | =head1 SEE ALSO | |
155 | ||
47bfe92f | 156 | L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<Encode> |
7d3b96bb NIS |
157 | |
158 | =cut | |
b3d30bf7 | 159 |