4 $open::hint_bits = 0x20000; # HINT_LOCALIZE_HH
8 require 5.008001; # for PerlIO::get_layers()
13 return ($1, Encode::resolve_alias($1)) if $_[0] =~ /^:?encoding\((.+)\)$/;
18 # If by the time we arrive here there already is at the top of the
19 # perlio layer stack an encoding identical to what we would like
20 # to push via this open pragma, we will pop away the old encoding
21 # (+utf8) so that we can push ourselves in place (this is easier
22 # than ignoring pushing ourselves because of the way how ${^OPEN}
23 # works). So we are looking for something like
25 # stdio encoding(xxx) utf8
27 # in the existing layer stack, and in the new stack chunk for
31 # If we find a match, we pop the old stack (once, since
32 # the utf8 is just a flag on the encoding layer)
34 return unless @new >= 1 && $new[-1] =~ /^:encoding\(.+\)$/;
35 my @old = PerlIO::get_layers($h);
36 return unless @old >= 3 &&
38 $old[-2] =~ /^encoding\(.+\)$/;
40 my ($loname, $lcname) = _get_encname($old[-2]);
41 unless (defined $lcname) { # Should we trust get_layers()?
43 Carp::croak("open: Unknown encoding '$loname'");
45 my ($voname, $vcname) = _get_encname($new[-1]);
46 unless (defined $vcname) {
48 Carp::croak("open: Unknown encoding '$voname'");
50 if ($lcname eq $vcname) {
51 binmode($h, ":pop"); # utf8 is part of the encoding layer
56 my ($class,@args) = @_;
57 croak("open: needs explicit list of PerlIO layers") unless @args;
59 $^H |= $open::hint_bits;
60 my ($in,$out) = split(/\0/,(${^OPEN} || "\0"), -1);
62 my $type = shift(@args);
64 if ($type =~ /^:?(utf8|locale|encoding\(.+\))$/) {
67 } elsif ($type eq ':std') {
71 $dscp = shift(@args) || '';
74 foreach my $layer (split(/\s+/,$dscp)) {
76 if ($layer eq 'locale') {
79 $locale_encoding = encoding::_get_locale_encoding()
80 unless defined $locale_encoding;
81 (warnings::warnif("layer", "Cannot figure out an encoding to use"), last)
82 unless defined $locale_encoding;
83 if ($locale_encoding =~ /^utf-?8$/i) {
86 $layer = "encoding($locale_encoding)";
90 my $target = $layer; # the layer name itself
91 $target =~ s/^(\w+)\(.+\)$/$1/; # strip parameters
93 unless(PerlIO::Layer::->find($target,1)) {
94 warnings::warnif("layer", "Unknown PerlIO layer '$target'");
98 if ($layer =~ /^(crlf|raw)$/) {
99 $^H{"open_$type"} = $layer;
103 _drop_oldenc(*STDIN, @val);
104 $in = join(' ', @val);
106 elsif ($type eq 'OUT') {
107 _drop_oldenc(*STDOUT, @val);
108 $out = join(' ', @val);
110 elsif ($type eq 'IO') {
111 _drop_oldenc(*STDIN, @val);
112 _drop_oldenc(*STDOUT, @val);
113 $in = $out = join(' ', @val);
116 croak "Unknown PerlIO layer class '$type'";
119 ${^OPEN} = join("\0", $in, $out);
122 if ($in =~ /:utf8\b/) {
123 binmode(STDIN, ":utf8");
124 } elsif ($in =~ /(\w+\(.+\))/) {
125 binmode(STDIN, ":$1");
129 if ($out =~ /:utf8\b/) {
130 binmode(STDOUT, ":utf8");
131 binmode(STDERR, ":utf8");
132 } elsif ($out =~ /(\w+\(.+\))/) {
133 binmode(STDOUT, ":$1");
134 binmode(STDERR, ":$1");
145 open - perl pragma to set default PerlIO layers for input and output
149 use open IN => ":crlf", OUT => ":bytes";
150 use open OUT => ':utf8';
151 use open IO => ":encoding(iso-8859-7)";
153 use open IO => ':locale';
157 use open ':encoding(iso-8859-7)';
163 Full-fledged support for I/O layers is now implemented provided
164 Perl is configured to use PerlIO as its IO system (which is now the
167 The C<open> pragma serves as one of the interfaces to declare default
168 "layers" (also known as "disciplines") for all I/O. Any two-argument
169 open(), readpipe() (aka qx//) and similar operators found within the
170 lexical scope of this pragma will use the declared defaults.
171 Three-argument opens are not affected by this pragma since there you
172 (can) explicitly specify the layers and are supposed to know what you
175 With the C<IN> subpragma you can declare the default layers
176 of input streams, and with the C<OUT> subpragma you can declare
177 the default layers of output streams. With the C<IO> subpragma
178 you can control both input and output streams simultaneously.
180 If you have a legacy encoding, you can use the C<:encoding(...)> tag.
182 if you want to set your encoding layers based on your
183 locale environment variables, you can use the C<:locale> tag.
186 $ENV{LANG} = 'ru_RU.KOI8-R';
187 # the :locale will probe the locale environment variables like LANG
188 use open OUT => ':locale';
190 print O chr(0x430); # Unicode CYRILLIC SMALL LETTER A = KOI8-R 0xc1
193 printf "%#x\n", ord(<I>), "\n"; # this should print 0xc1
199 use open IO => ':utf8';
204 use open IO => ':locale';
208 use open ':encoding(iso-8859-7)';
209 use open IO => ':encoding(iso-8859-7)';
211 The matching of encoding names is loose: case does not matter, and
212 many encodings have several aliases. See L<Encode::Supported> for
213 details and the list of supported locales.
215 Note that C<:utf8> PerlIO layer must always be specified exactly like
216 that, it is not subject to the loose matching of encoding names.
218 When open() is given an explicit list of layers they are appended to
219 the list declared using this pragma.
221 The C<:std> subpragma on its own has no effect, but if combined with
222 the C<:utf8> or C<:encoding> subpragmas, it converts the standard
223 filehandles (STDIN, STDOUT, STDERR) to comply with encoding selected
224 for input/output handles. For example, if both input and out are
225 chosen to be C<:utf8>, a C<:std> will mean that STDIN, STDOUT, and
226 STDERR are also in C<:utf8>. On the other hand, if only output is
227 chosen to be in C<< :encoding(koi8r) >>, a C<:std> will cause only the
228 STDOUT and STDERR to be in C<koi8r>. The C<:locale> subpragma
229 implicitly turns on C<:std>.
231 The logic of C<:locale> is described in full in L</encoding>,
232 but in short it is first trying nl_langinfo(CODESET) and then
233 guessing from the LC_ALL and LANG locale environment variables.
235 Directory handles may also support PerlIO layers in the future.
237 =head1 NONPERLIO FUNCTIONALITY
239 If Perl is not built to use PerlIO as its IO system then only the two
240 pseudo-layers C<:bytes> and C<:crlf> are available.
242 The C<:bytes> layer corresponds to "binary mode" and the C<:crlf>
243 layer corresponds to "text mode" on platforms that distinguish
244 between the two modes when opening files (which is many DOS-like
245 platforms, including Windows). These two layers are no-ops on
246 platforms where binmode() is a no-op, but perform their functions
247 everywhere if PerlIO is enabled.
249 =head1 IMPLEMENTATION DETAILS
251 There is a class method in C<PerlIO::Layer> C<find> which is
252 implemented as XS code. It is called by C<import> to validate the
255 PerlIO::Layer::->find("perlio")
257 The return value (if defined) is a Perl object, of class
258 C<PerlIO::Layer> which is created by the C code in F<perlio.c>. As
259 yet there is nothing useful you can do with the object at the perl
264 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<PerlIO>,