4 $open::hint_bits = 0x20000;
10 sub in_locale { $^H & ($locale::hint_bits || 0)}
12 sub _get_locale_encoding {
13 unless (defined $locale_encoding) {
14 # I18N::Langinfo isn't available everywhere
16 require I18N::Langinfo;
17 I18N::Langinfo->import(qw(langinfo CODESET));
18 $locale_encoding = langinfo(CODESET());
22 no warnings 'uninitialized';
24 if (not $locale_encoding && in_locale()) {
25 if ($ENV{LC_ALL} =~ /^([^.]+)\.([^.]+)$/) {
26 ($country_language, $locale_encoding) = ($1, $2);
27 } elsif ($ENV{LANG} =~ /^([^.]+)\.([^.]+)$/) {
28 ($country_language, $locale_encoding) = ($1, $2);
30 } elsif (not $locale_encoding) {
31 if ($ENV{LC_ALL} =~ /\butf-?8\b/i ||
32 $ENV{LANG} =~ /\butf-?8\b/i) {
33 $locale_encoding = 'utf8';
35 # Could do more heuristics based on the country and language
36 # parts of LC_ALL and LANG (the parts before the dot (if any)),
37 # since we have Locale::Country and Locale::Language available.
38 # TODO: get a database of Language -> Encoding mappings
39 # (the Estonian database at http://www.eki.ee/letter/
40 # would be excellent!) --jhi
42 if (defined $locale_encoding &&
43 $locale_encoding eq 'euc' &&
44 defined $country_language) {
45 if ($country_language =~ /^ja_JP|japan(?:ese)?$/i) {
46 $locale_encoding = 'euc-jp';
47 } elsif ($country_language =~ /^ko_KR|korean?$/i) {
48 $locale_encoding = 'euc-kr';
49 } elsif ($country_language =~ /^zh_CN|chin(?:a|ese)?$/i) {
50 $locale_encoding = 'euc-cn';
51 } elsif ($country_language =~ /^zh_TW|taiwan(?:ese)?$/i) {
52 $locale_encoding = 'euc-tw';
54 croak "Locale encoding 'euc' too ambiguous"
55 if $locale_encoding eq 'euc';
61 my ($class,@args) = @_;
62 croak("`use open' needs explicit list of PerlIO layers") unless @args;
64 $^H |= $open::hint_bits;
65 my ($in,$out) = split(/\0/,(${^OPEN} || "\0"), -1);
67 my $type = shift(@args);
69 if ($type =~ /^:?(utf8|locale|encoding\(.+\))$/) {
72 } elsif ($type eq ':std') {
76 $dscp = shift(@args) || '';
79 foreach my $layer (split(/\s+/,$dscp)) {
81 if ($layer eq 'locale') {
83 _get_locale_encoding()
84 unless defined $locale_encoding;
85 (warnings::warnif("layer", "Cannot figure out an encoding to use"), last)
86 unless defined $locale_encoding;
87 if ($locale_encoding =~ /^utf-?8$/i) {
90 $layer = "encoding($locale_encoding)";
94 my $target = $layer; # the layer name itself
95 $target =~ s/^(\w+)\(.+\)$/$1/; # strip parameters
97 unless(PerlIO::Layer::->find($target)) {
98 warnings::warnif("layer", "Unknown PerlIO layer '$layer'");
101 push(@val,":$layer");
102 if ($layer =~ /^(crlf|raw)$/) {
103 $^H{"open_$type"} = $layer;
107 $in = join(' ',@val);
109 elsif ($type eq 'OUT') {
110 $out = join(' ',@val);
112 elsif ($type eq 'IO') {
113 $in = $out = join(' ',@val);
116 croak "Unknown PerlIO layer class '$type'";
119 ${^OPEN} = join("\0",$in,$out) if $in or $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 open(),
169 readpipe() (aka qx//) and similar operators found within the lexical
170 scope of this pragma will use the declared defaults.
172 With the C<IN> subpragma you can declare the default layers
173 of input streams, and with the C<OUT> subpragma you can declare
174 the default layers of output streams. With the C<IO> subpragma
175 you can control both input and output streams simultaneously.
177 If you have a legacy encoding, you can use the C<:encoding(...)> tag.
179 if you want to set your encoding layers based on your
180 locale environment variables, you can use the C<:locale> tag.
183 $ENV{LANG} = 'ru_RU.KOI8-R';
184 # the :locale will probe the locale environment variables like LANG
185 use open OUT => ':locale';
187 print O chr(0x430); # Unicode CYRILLIC SMALL LETTER A = KOI8-R 0xc1
190 printf "%#x\n", ord(<I>), "\n"; # this should print 0xc1
196 use open IO => ':utf8';
201 use open IO => ':locale';
205 use open ':encoding(iso-8859-7)';
206 use open IO => ':encoding(iso-8859-7)';
208 The matching of encoding names is loose: case does not matter, and
209 many encodings have several aliases. See L<Encode::Supported> for
210 details and the list of supported locales.
212 Note that C<:utf8> PerlIO layer must always be specified exactly like
213 that, it is not subject to the loose matching of encoding names.
215 When open() is given an explicit list of layers they are appended to
216 the list declared using this pragma.
218 The C<:std> subpragma on its own has no effect, but if combined with
219 the C<:utf8> or C<:encoding> subpragmas, it converts the standard
220 filehandles (STDIN, STDOUT, STDERR) to comply with encoding selected
221 for input/output handles. For example, if both input and out are
222 chosen to be C<:utf8>, a C<:std> will mean that STDIN, STDOUT, and
223 STDERR are also in C<:utf8>. On the other hand, if only output is
224 chosen to be in C<< :encoding(koi8r) >>, a C<:std> will cause only the
225 STDOUT and STDERR to be in C<koi8r>. The C<:locale> subpragma
226 implicitly turns on C<:std>.
228 The logic of C<:locale> is as follows:
234 If the platform supports the langinfo(CODESET) interface, the codeset
235 returned is used as the default encoding for the open pragma.
239 If 1. didn't work but we are under the locale pragma, the environment
240 variables LC_ALL and LANG (in that order) are matched for encodings
241 (the part after C<.>, if any), and if any found, that is used
242 as the default encoding for the open pragma.
246 If 1. and 2. didn't work, the environment variables LC_ALL and LANG
247 (in that order) are matched for anything looking like UTF-8, and if
248 any found, C<:utf8> is used as the default encoding for the open
253 If your locale environment variables (LANGUAGE, LC_ALL, LC_CTYPE, LANG)
254 contain the strings 'UTF-8' or 'UTF8' (case-insensitive matching),
255 the default encoding of your STDIN, STDOUT, and STDERR, and of
256 B<any subsequent file open>, is UTF-8.
258 Directory handles may also support PerlIO layers in the future.
260 =head1 NONPERLIO FUNCTIONALITY
262 If Perl is not built to use PerlIO as its IO system then only the two
263 pseudo-layers C<:bytes> and C<:crlf> are available.
265 The C<:bytes> layer corresponds to "binary mode" and the C<:crlf>
266 layer corresponds to "text mode" on platforms that distinguish
267 between the two modes when opening files (which is many DOS-like
268 platforms, including Windows). These two layers are no-ops on
269 platforms where binmode() is a no-op, but perform their functions
270 everywhere if PerlIO is enabled.
272 =head1 IMPLEMENTATION DETAILS
274 There is a class method in C<PerlIO::Layer> C<find> which is
275 implemented as XS code. It is called by C<import> to validate the
278 PerlIO::Layer::->find("perlio")
280 The return value (if defined) is a Perl object, of class
281 C<PerlIO::Layer> which is created by the C code in F<perlio.c>. As
282 yet there is nothing useful you can do with the object at the perl
287 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<PerlIO>,