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