3 $open::hint_bits = 0x20000; # HINT_LOCALIZE_HH
7 require 5.008001; # for PerlIO::get_layers()
12 return ($1, Encode::resolve_alias($1)) if $_[0] =~ /^:?encoding\((.+)\)$/;
17 require Carp; goto &Carp::croak;
21 # If by the time we arrive here there already is at the top of the
22 # perlio layer stack an encoding identical to what we would like
23 # to push via this open pragma, we will pop away the old encoding
24 # (+utf8) so that we can push ourselves in place (this is easier
25 # than ignoring pushing ourselves because of the way how ${^OPEN}
26 # works). So we are looking for something like
28 # stdio encoding(xxx) utf8
30 # in the existing layer stack, and in the new stack chunk for
34 # If we find a match, we pop the old stack (once, since
35 # the utf8 is just a flag on the encoding layer)
37 return unless @new >= 1 && $new[-1] =~ /^:encoding\(.+\)$/;
38 my @old = PerlIO::get_layers($h);
39 return unless @old >= 3 &&
41 $old[-2] =~ /^encoding\(.+\)$/;
43 my ($loname, $lcname) = _get_encname($old[-2]);
44 unless (defined $lcname) { # Should we trust get_layers()?
45 croak("open: Unknown encoding '$loname'");
47 my ($voname, $vcname) = _get_encname($new[-1]);
48 unless (defined $vcname) {
49 croak("open: Unknown encoding '$voname'");
51 if ($lcname eq $vcname) {
52 binmode($h, ":pop"); # utf8 is part of the encoding layer
57 my ($class,@args) = @_;
58 croak("open: needs explicit list of PerlIO layers") unless @args;
60 $^H |= $open::hint_bits;
61 my ($in,$out) = split(/\0/,(${^OPEN} || "\0"), -1);
63 my $type = shift(@args);
65 if ($type =~ /^:?(utf8|locale|encoding\(.+\))$/) {
68 } elsif ($type eq ':std') {
72 $dscp = shift(@args) || '';
75 foreach my $layer (split(/\s+/,$dscp)) {
77 if ($layer eq 'locale') {
80 $locale_encoding = encoding::_get_locale_encoding()
81 unless defined $locale_encoding;
82 (warnings::warnif("layer", "Cannot figure out an encoding to use"), last)
83 unless defined $locale_encoding;
84 if ($locale_encoding =~ /^utf-?8$/i) {
87 $layer = "encoding($locale_encoding)";
91 my $target = $layer; # the layer name itself
92 $target =~ s/^(\w+)\(.+\)$/$1/; # strip parameters
94 unless(PerlIO::Layer::->find($target,1)) {
95 warnings::warnif("layer", "Unknown PerlIO layer '$target'");
99 if ($layer =~ /^(crlf|raw)$/) {
100 $^H{"open_$type"} = $layer;
104 _drop_oldenc(*STDIN, @val);
105 $in = join(' ', @val);
107 elsif ($type eq 'OUT') {
108 _drop_oldenc(*STDOUT, @val);
109 $out = join(' ', @val);
111 elsif ($type eq 'IO') {
112 _drop_oldenc(*STDIN, @val);
113 _drop_oldenc(*STDOUT, @val);
114 $in = $out = join(' ', @val);
117 croak "Unknown PerlIO layer class '$type'";
120 ${^OPEN} = join("\0", $in, $out);
123 if ($in =~ /:utf8\b/) {
124 binmode(STDIN, ":utf8");
125 } elsif ($in =~ /(\w+\(.+\))/) {
126 binmode(STDIN, ":$1");
130 if ($out =~ /:utf8\b/) {
131 binmode(STDOUT, ":utf8");
132 binmode(STDERR, ":utf8");
133 } elsif ($out =~ /(\w+\(.+\))/) {
134 binmode(STDOUT, ":$1");
135 binmode(STDERR, ":$1");
146 open - perl pragma to set default PerlIO layers for input and output
150 use open IN => ":crlf", OUT => ":bytes";
151 use open OUT => ':utf8';
152 use open IO => ":encoding(iso-8859-7)";
154 use open IO => ':locale';
158 use open ':encoding(iso-8859-7)';
164 Full-fledged support for I/O layers is now implemented provided
165 Perl is configured to use PerlIO as its IO system (which is now the
168 The C<open> pragma serves as one of the interfaces to declare default
169 "layers" (also known as "disciplines") for all I/O. Any two-argument
170 open(), readpipe() (aka qx//) and similar operators found within the
171 lexical scope of this pragma will use the declared defaults.
172 Even three-argument opens may be affected by this pragma
173 when they don't specify IO layers in MODE.
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 (with the three-arg
219 syntax), they override 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>,