This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Ooops. It helps to p4 add the new file.
[perl5.git] / ext / Encode / encoding.pm
CommitLineData
51e4e64d 1# $Id: encoding.pm,v 2.5 2007/04/06 12:53:41 dankogai Exp dankogai $
3ef515df 2package encoding;
51e4e64d 3our $VERSION = do { my @r = ( q$Revision: 2.5 $ =~ /\d+/g ); sprintf "%d." . "%02d" x $#r, @r };
3ef515df
JH
4
5use Encode;
046f36bf 6use strict;
656ebd29 7use warnings;
b1aeb384 8
8f139f4c 9sub DEBUG () { 0 }
3ef515df
JH
10
11BEGIN {
d1256cb1
RGS
12 if ( ord("A") == 193 ) {
13 require Carp;
14 Carp::croak("encoding: pragma does not support EBCDIC platforms");
3ef515df
JH
15 }
16}
17
0ab8f81e
JH
18our $HAS_PERLIO = 0;
19eval { require PerlIO::encoding };
d1256cb1
RGS
20unless ($@) {
21 $HAS_PERLIO = ( PerlIO::encoding->VERSION >= 0.02 );
0ab8f81e 22}
b2704119 23
d1256cb1 24sub _exception {
151b5d36 25 my $name = shift;
d1256cb1
RGS
26 $] > 5.008 and return 0; # 5.8.1 or higher then no
27 my %utfs = map { $_ => 1 }
28 qw(utf8 UCS-2BE UCS-2LE UTF-16 UTF-16BE UTF-16LE
29 UTF-32 UTF-32BE UTF-32LE);
30 $utfs{$name} or return 0; # UTFs or no
31 require Config;
32 Config->import();
33 our %Config;
34 return $Config{perl_patchlevel} ? 0 : 1 # maintperl then no
151b5d36 35}
fa6f41cf 36
d1256cb1 37sub in_locale { $^H & ( $locale::hint_bits || 0 ) }
b1aeb384
JH
38
39sub _get_locale_encoding {
40 my $locale_encoding;
41
42 # I18N::Langinfo isn't available everywhere
43 eval {
d1256cb1
RGS
44 require I18N::Langinfo;
45 I18N::Langinfo->import(qw(langinfo CODESET));
46 $locale_encoding = langinfo( CODESET() );
b1aeb384 47 };
d1256cb1 48
b1aeb384
JH
49 my $country_language;
50
51 no warnings 'uninitialized';
52
d1256cb1
RGS
53 if ( not $locale_encoding && in_locale() ) {
54 if ( $ENV{LC_ALL} =~ /^([^.]+)\.([^.]+)$/ ) {
55 ( $country_language, $locale_encoding ) = ( $1, $2 );
56 }
57 elsif ( $ENV{LANG} =~ /^([^.]+)\.([^.]+)$/ ) {
58 ( $country_language, $locale_encoding ) = ( $1, $2 );
59 }
60
61 # LANGUAGE affects only LC_MESSAGES only on glibc
62 }
63 elsif ( not $locale_encoding ) {
64 if ( $ENV{LC_ALL} =~ /\butf-?8\b/i
65 || $ENV{LANG} =~ /\butf-?8\b/i )
66 {
67 $locale_encoding = 'utf8';
68 }
69
70 # Could do more heuristics based on the country and language
71 # parts of LC_ALL and LANG (the parts before the dot (if any)),
72 # since we have Locale::Country and Locale::Language available.
73 # TODO: get a database of Language -> Encoding mappings
74 # (the Estonian database at http://www.eki.ee/letter/
75 # would be excellent!) --jhi
b1aeb384 76 }
d1256cb1
RGS
77 if ( defined $locale_encoding
78 && lc($locale_encoding) eq 'euc'
79 && defined $country_language )
80 {
81 if ( $country_language =~ /^ja_JP|japan(?:ese)?$/i ) {
82 $locale_encoding = 'euc-jp';
83 }
84 elsif ( $country_language =~ /^ko_KR|korean?$/i ) {
85 $locale_encoding = 'euc-kr';
86 }
5a1dbf39 87 elsif ( $country_language =~ /^zh_CN|chin(?:a|ese)$/i ) {
d1256cb1
RGS
88 $locale_encoding = 'euc-cn';
89 }
90 elsif ( $country_language =~ /^zh_TW|taiwan(?:ese)?$/i ) {
91 $locale_encoding = 'euc-tw';
92 }
93 else {
94 require Carp;
95 Carp::croak(
96 "encoding: Locale encoding '$locale_encoding' too ambiguous"
97 );
98 }
b1aeb384
JH
99 }
100
101 return $locale_encoding;
102}
103
3ef515df
JH
104sub import {
105 my $class = shift;
106 my $name = shift;
d1256cb1
RGS
107 if ( $name eq ':_get_locale_encoding' ) { # used by lib/open.pm
108 my $caller = caller();
b1aeb384 109 {
d1256cb1
RGS
110 no strict 'refs';
111 *{"${caller}::_get_locale_encoding"} = \&_get_locale_encoding;
112 }
113 return;
b1aeb384
JH
114 }
115 $name = _get_locale_encoding() if $name eq ':locale';
3ef515df 116 my %arg = @_;
b1aeb384 117 $name = $ENV{PERL_ENCODING} unless defined $name;
3ef515df 118 my $enc = find_encoding($name);
d1256cb1
RGS
119 unless ( defined $enc ) {
120 require Carp;
121 Carp::croak("encoding: Unknown encoding '$name'");
122 }
123 $name = $enc->name; # canonize
124 unless ( $arg{Filter} ) {
125 DEBUG and warn "_exception($name) = ", _exception($name);
126 _exception($name) or ${^ENCODING} = $enc;
127 $HAS_PERLIO or return 1;
3ef515df 128 }
d1256cb1
RGS
129 else {
130 defined( ${^ENCODING} ) and undef ${^ENCODING};
131
132 # implicitly 'use utf8'
133 require utf8; # to fetch $utf8::hint_bits;
134 $^H |= $utf8::hint_bits;
135 eval {
136 require Filter::Util::Call;
137 Filter::Util::Call->import;
138 filter_add(
139 sub {
140 my $status = filter_read();
141 if ( $status > 0 ) {
142 $_ = $enc->decode( $_, 1 );
143 DEBUG and warn $_;
144 }
145 $status;
146 }
147 );
148 };
d7fe8a7a 149 $@ eq '' and DEBUG and warn "Filter installed";
b1aeb384 150 }
05ef2f67 151 defined ${^UNICODE} and ${^UNICODE} != 0 and return 1;
d1256cb1
RGS
152 for my $h (qw(STDIN STDOUT)) {
153 if ( $arg{$h} ) {
154 unless ( defined find_encoding( $arg{$h} ) ) {
155 require Carp;
156 Carp::croak(
157 "encoding: Unknown encoding for $h, '$arg{$h}'");
158 }
159 eval { binmode( $h, ":raw :encoding($arg{$h})" ) };
160 }
161 else {
162 unless ( exists $arg{$h} ) {
163 eval {
164 no warnings 'uninitialized';
165 binmode( $h, ":raw :encoding($name)" );
166 };
167 }
168 }
169 if ($@) {
170 require Carp;
171 Carp::croak($@);
172 }
3ef515df 173 }
d1256cb1 174 return 1; # I doubt if we need it, though
3ef515df
JH
175}
176
d1256cb1 177sub unimport {
3ef515df
JH
178 no warnings;
179 undef ${^ENCODING};
d1256cb1
RGS
180 if ($HAS_PERLIO) {
181 binmode( STDIN, ":raw" );
182 binmode( STDOUT, ":raw" );
183 }
184 else {
185 binmode(STDIN);
186 binmode(STDOUT);
621b0f8d 187 }
d1256cb1
RGS
188 if ( $INC{"Filter/Util/Call.pm"} ) {
189 eval { filter_del() };
aae85ceb 190 }
3ef515df
JH
191}
192
1931;
194__END__
85982a32 195
3ef515df
JH
196=pod
197
198=head1 NAME
199
0ab8f81e 200encoding - allows you to write your script in non-ascii or non-utf8
3ef515df
JH
201
202=head1 SYNOPSIS
203
962111ca 204 use encoding "greek"; # Perl like Greek to you?
3ef515df
JH
205 use encoding "euc-jp"; # Jperl!
206
962111ca 207 # or you can even do this if your shell supports your native encoding
3ef515df 208
962111ca 209 perl -Mencoding=latin2 -e '...' # Feeling centrally European?
0ab8f81e 210 perl -Mencoding=euc-kr -e '...' # Or Korean?
3ef515df 211
3ef515df
JH
212 # more control
213
962111ca 214 # A simple euc-cn => utf-8 converter
6d1c0808 215 use encoding "euc-cn", STDOUT => "utf8"; while(<>){print};
3ef515df
JH
216
217 # "no encoding;" supported (but not scoped!)
218 no encoding;
219
aae85ceb
DK
220 # an alternate way, Filter
221 use encoding "euc-jp", Filter=>1;
aae85ceb
DK
222 # now you can use kanji identifiers -- in euc-jp!
223
b1aeb384
JH
224 # switch on locale -
225 # note that this probably means that unless you have a complete control
226 # over the environments the application is ever going to be run, you should
227 # NOT use the feature of encoding pragma allowing you to write your script
228 # in any recognized encoding because changing locale settings will wreck
229 # the script; you can of course still use the other features of the pragma.
230 use encoding ':locale';
231
3ef515df
JH
232=head1 ABSTRACT
233
962111ca
JH
234Let's start with a bit of history: Perl 5.6.0 introduced Unicode
235support. You could apply C<substr()> and regexes even to complex CJK
236characters -- so long as the script was written in UTF-8. But back
0ab8f81e
JH
237then, text editors that supported UTF-8 were still rare and many users
238instead chose to write scripts in legacy encodings, giving up a whole
239new feature of Perl 5.6.
3ef515df 240
0ab8f81e 241Rewind to the future: starting from perl 5.8.0 with the B<encoding>
962111ca
JH
242pragma, you can write your script in any encoding you like (so long
243as the C<Encode> module supports it) and still enjoy Unicode support.
0f29a567 244This pragma achieves that by doing the following:
05ef2f67
JH
245
246=over
247
248=item *
249
250Internally converts all literals (C<q//,qq//,qr//,qw///, qx//>) from
251the encoding specified to utf8. In Perl 5.8.1 and later, literals in
252C<tr///> and C<DATA> pseudo-filehandle are also converted.
253
254=item *
255
256Changing PerlIO layers of C<STDIN> and C<STDOUT> to the encoding
257 specified.
258
259=back
260
261=head2 Literal Conversions
262
0ab8f81e 263You can write code in EUC-JP as follows:
3ef515df
JH
264
265 my $Rakuda = "\xF1\xD1\xF1\xCC"; # Camel in Kanji
266 #<-char-><-char-> # 4 octets
267 s/\bCamel\b/$Rakuda/;
268
269And with C<use encoding "euc-jp"> in effect, it is the same thing as
962111ca 270the code in UTF-8:
3ef515df 271
32b9ed1f 272 my $Rakuda = "\x{99F1}\x{99DD}"; # two Unicode Characters
3ef515df
JH
273 s/\bCamel\b/$Rakuda/;
274
05ef2f67
JH
275=head2 PerlIO layers for C<STD(IN|OUT)>
276
277The B<encoding> pragma also modifies the filehandle layers of
4b291ae6 278STDIN and STDOUT to the specified encoding. Therefore,
3ef515df
JH
279
280 use encoding "euc-jp";
281 my $message = "Camel is the symbol of perl.\n";
282 my $Rakuda = "\xF1\xD1\xF1\xCC"; # Camel in Kanji
283 $message =~ s/\bCamel\b/$Rakuda/;
284 print $message;
285
962111ca
JH
286Will print "\xF1\xD1\xF1\xCC is the symbol of perl.\n",
287not "\x{99F1}\x{99DD} is the symbol of perl.\n".
3ef515df 288
0ab8f81e 289You can override this by giving extra arguments; see below.
3ef515df 290
990e18f7
AT
291=head2 Implicit upgrading for byte strings
292
293By default, if strings operating under byte semantics and strings
294with Unicode character data are concatenated, the new string will
295be created by decoding the byte strings as I<ISO 8859-1 (Latin-1)>.
296
297The B<encoding> pragma changes this to use the specified encoding
298instead. For example:
299
300 use encoding 'utf8';
301 my $string = chr(20000); # a Unicode string
302 utf8::encode($string); # now it's a UTF-8 encoded byte string
303 # concatenate with another Unicode string
304 print length($string . chr(20000));
305
306Will print C<2>, because C<$string> is upgraded as UTF-8. Without
307C<use encoding 'utf8';>, it will print C<4> instead, since C<$string>
308is three octets when interpreted as Latin-1.
309
2575c402
JW
310=head2 Side effects
311
312If the C<encoding> pragma is in scope then the lengths returned are
313calculated from the length of C<$/> in Unicode characters, which is not
314always the same as the length of C<$/> in the native encoding.
315
316This pragma affects utf8::upgrade, but not utf8::downgrade.
317
51e4e64d
NC
318=head2 Side effects
319
320If the C<encoding> pragma is in scope then the lengths returned are
321calculated from the length of C<$/> in Unicode characters, which is not
322always the same as the length of C<$/> in the native encoding.
323
324This pragma affects utf8::upgrade, but not utf8::downgrade.
325
05ef2f67
JH
326=head1 FEATURES THAT REQUIRE 5.8.1
327
328Some of the features offered by this pragma requires perl 5.8.1. Most
0f29a567 329of these are done by Inaba Hiroto. Any other features and changes
05ef2f67
JH
330are good for 5.8.0.
331
332=over
333
334=item "NON-EUC" doublebyte encodings
335
0f29a567 336Because perl needs to parse script before applying this pragma, such
05ef2f67
JH
337encodings as Shift_JIS and Big-5 that may contain '\' (BACKSLASH;
338\x5c) in the second byte fails because the second byte may
0f29a567 339accidentally escape the quoting character that follows. Perl 5.8.1
05ef2f67
JH
340or later fixes this problem.
341
342=item tr//
343
344C<tr//> was overlooked by Perl 5 porters when they released perl 5.8.0
345See the section below for details.
346
347=item DATA pseudo-filehandle
348
349Another feature that was overlooked was C<DATA>.
350
351=back
352
3ef515df
JH
353=head1 USAGE
354
355=over 4
356
357=item use encoding [I<ENCNAME>] ;
358
05ef2f67
JH
359Sets the script encoding to I<ENCNAME>. And unless ${^UNICODE}
360exists and non-zero, PerlIO layers of STDIN and STDOUT are set to
361":encoding(I<ENCNAME>)".
362
363Note that STDERR WILL NOT be changed.
364
365Also note that non-STD file handles remain unaffected. Use C<use
366open> or C<binmode> to change layers of those.
3ef515df
JH
367
368If no encoding is specified, the environment variable L<PERL_ENCODING>
962111ca
JH
369is consulted. If no encoding can be found, the error C<Unknown encoding
370'I<ENCNAME>'> will be thrown.
3ef515df 371
aae85ceb 372=item use encoding I<ENCNAME> [ STDIN =E<gt> I<ENCNAME_IN> ...] ;
3ef515df 373
0ab8f81e 374You can also individually set encodings of STDIN and STDOUT via the
32b9ed1f
A
375C<< STDIN => I<ENCNAME> >> form. In this case, you cannot omit the
376first I<ENCNAME>. C<< STDIN => undef >> turns the IO transcoding
aae85ceb 377completely off.
3ef515df 378
05ef2f67
JH
379When ${^UNICODE} exists and non-zero, these options will completely
380ignored. ${^UNICODE} is a variable introduced in perl 5.8.1. See
381L<perlrun> see L<perlvar/"${^UNICODE}"> and L<perlrun/"-C"> for
382details (perl 5.8.1 and later).
383
151b5d36
JH
384=item use encoding I<ENCNAME> Filter=E<gt>1;
385
386This turns the encoding pragma into a source filter. While the
387default approach just decodes interpolated literals (in qq() and
388qr()), this will apply a source filter to the entire source code. See
05ef2f67 389L</"The Filter Option"> below for details.
151b5d36 390
3ef515df
JH
391=item no encoding;
392
05ef2f67 393Unsets the script encoding. The layers of STDIN, STDOUT are
962111ca 394reset to ":raw" (the default unprocessed raw stream of bytes).
3ef515df
JH
395
396=back
397
151b5d36
JH
398=head1 The Filter Option
399
400The magic of C<use encoding> is not applied to the names of
401identifiers. In order to make C<${"\x{4eba}"}++> ($human++, where human
402is a single Han ideograph) work, you still need to write your script
403in UTF-8 -- or use a source filter. That's what 'Filter=>1' does.
404
151b5d36
JH
405What does this mean? Your source code behaves as if it is written in
406UTF-8 with 'use utf8' in effect. So even if your editor only supports
407Shift_JIS, for example, you can still try examples in Chapter 15 of
408C<Programming Perl, 3rd Ed.>. For instance, you can use UTF-8
409identifiers.
410
411This option is significantly slower and (as of this writing) non-ASCII
412identifiers are not very stable WITHOUT this option and with the
413source code written in UTF-8.
414
415=head2 Filter-related changes at Encode version 1.87
416
417=over
418
419=item *
420
421The Filter option now sets STDIN and STDOUT like non-filter options.
422And C<< STDIN=>I<ENCODING> >> and C<< STDOUT=>I<ENCODING> >> work like
423non-filter version.
424
425=item *
426
427C<use utf8> is implicitly declared so you no longer have to C<use
428utf8> to C<${"\x{4eba}"}++>.
429
430=back
431
3ef515df
JH
432=head1 CAVEATS
433
434=head2 NOT SCOPED
435
436The pragma is a per script, not a per block lexical. Only the last
621b0f8d
DK
437C<use encoding> or C<no encoding> matters, and it affects
438B<the whole script>. However, the <no encoding> pragma is supported and
439B<use encoding> can appear as many times as you want in a given script.
440The multiple use of this pragma is discouraged.
441
0f29a567 442By the same reason, the use this pragma inside modules is also
3c4b39be 443discouraged (though not as strongly discouraged as the case above.
0f29a567 444See below).
05ef2f67
JH
445
446If you still have to write a module with this pragma, be very careful
447of the load order. See the codes below;
448
449 # called module
450 package Module_IN_BAR;
451 use encoding "bar";
452 # stuff in "bar" encoding here
453 1;
454
455 # caller script
456 use encoding "foo"
457 use Module_IN_BAR;
458 # surprise! use encoding "bar" is in effect.
459
460The best way to avoid this oddity is to use this pragma RIGHT AFTER
461other modules are loaded. i.e.
462
463 use Module_IN_BAR;
464 use encoding "foo";
3ef515df
JH
465
466=head2 DO NOT MIX MULTIPLE ENCODINGS
467
468Notice that only literals (string or regular expression) having only
469legacy code points are affected: if you mix data like this
470
d1256cb1 471 \xDF\x{100}
3ef515df
JH
472
473the data is assumed to be in (Latin 1 and) Unicode, not in your native
474encoding. In other words, this will match in "greek":
475
d1256cb1 476 "\xDF" =~ /\x{3af}/
3ef515df
JH
477
478but this will not
479
d1256cb1 480 "\xDF\x{100}" =~ /\x{3af}\x{100}/
3ef515df 481
962111ca
JH
482since the C<\xDF> (ISO 8859-7 GREEK SMALL LETTER IOTA WITH TONOS) on
483the left will B<not> be upgraded to C<\x{3af}> (Unicode GREEK SMALL
484LETTER IOTA WITH TONOS) because of the C<\x{100}> on the left. You
485should not be mixing your legacy data and Unicode in the same string.
3ef515df
JH
486
487This pragma also affects encoding of the 0x80..0xFF code point range:
488normally characters in that range are left as eight-bit bytes (unless
489they are combined with characters with code points 0x100 or larger,
490in which case all characters need to become UTF-8 encoded), but if
491the C<encoding> pragma is present, even the 0x80..0xFF range always
492gets UTF-8 encoded.
493
494After all, the best thing about this pragma is that you don't have to
0ab8f81e
JH
495resort to \x{....} just to spell your name in a native encoding.
496So feel free to put your strings in your encoding in quotes and
497regexes.
3ef515df 498
151b5d36 499=head2 tr/// with ranges
4b291ae6
DK
500
501The B<encoding> pragma works by decoding string literals in
151b5d36 502C<q//,qq//,qr//,qw///, qx//> and so forth. In perl 5.8.0, this
4b291ae6
DK
503does not apply to C<tr///>. Therefore,
504
505 use encoding 'euc-jp';
506 #....
507 $kana =~ tr/\xA4\xA1-\xA4\xF3/\xA5\xA1-\xA5\xF3/;
508 # -------- -------- -------- --------
509
510Does not work as
511
512 $kana =~ tr/\x{3041}-\x{3093}/\x{30a1}-\x{30f3}/;
513
514=over
515
516=item Legend of characters above
517
518 utf8 euc-jp charnames::viacode()
519 -----------------------------------------
520 \x{3041} \xA4\xA1 HIRAGANA LETTER SMALL A
521 \x{3093} \xA4\xF3 HIRAGANA LETTER N
522 \x{30a1} \xA5\xA1 KATAKANA LETTER SMALL A
523 \x{30f3} \xA5\xF3 KATAKANA LETTER N
524
525=back
526
05ef2f67 527This counterintuitive behavior has been fixed in perl 5.8.1.
151b5d36 528
4b291ae6
DK
529=head3 workaround to tr///;
530
ce16148b 531In perl 5.8.0, you can work around as follows;
4b291ae6
DK
532
533 use encoding 'euc-jp';
151b5d36 534 # ....
4b291ae6
DK
535 eval qq{ \$kana =~ tr/\xA4\xA1-\xA4\xF3/\xA5\xA1-\xA5\xF3/ };
536
ce16148b 537Note the C<tr//> expression is surrounded by C<qq{}>. The idea behind
4b291ae6
DK
538is the same as classic idiom that makes C<tr///> 'interpolate'.
539
540 tr/$from/$to/; # wrong!
541 eval qq{ tr/$from/$to/ }; # workaround.
542
543Nevertheless, in case of B<encoding> pragma even C<q//> is affected so
544C<tr///> not being decoded was obviously against the will of Perl5
05ef2f67 545Porters so it has been fixed in Perl 5.8.1 or later.
aae85ceb 546
3ef515df
JH
547=head1 EXAMPLE - Greekperl
548
549 use encoding "iso 8859-7";
550
0ab8f81e 551 # \xDF in ISO 8859-7 (Greek) is \x{3af} in Unicode.
3ef515df
JH
552
553 $a = "\xDF";
554 $b = "\x{100}";
555
556 printf "%#x\n", ord($a); # will print 0x3af, not 0xdf
557
558 $c = $a . $b;
559
560 # $c will be "\x{3af}\x{100}", not "\x{df}\x{100}".
561
562 # chr() is affected, and ...
563
564 print "mega\n" if ord(chr(0xdf)) == 0x3af;
565
566 # ... ord() is affected by the encoding pragma ...
567
568 print "tera\n" if ord(pack("C", 0xdf)) == 0x3af;
569
570 # ... as are eq and cmp ...
571
572 print "peta\n" if "\x{3af}" eq pack("C", 0xdf);
573 print "exa\n" if "\x{3af}" cmp pack("C", 0xdf) == 0;
574
575 # ... but pack/unpack C are not affected, in case you still
0ab8f81e 576 # want to go back to your native encoding
3ef515df
JH
577
578 print "zetta\n" if unpack("C", (pack("C", 0xdf))) == 0xdf;
579
580=head1 KNOWN PROBLEMS
581
151b5d36
JH
582=over
583
0f29a567 584=item literals in regex that are longer than 127 bytes
151b5d36 585
0ab8f81e 586For native multibyte encodings (either fixed or variable length),
3ef515df 587the current implementation of the regular expressions may introduce
0ab8f81e 588recoding errors for regular expression literals longer than 127 bytes.
3ef515df 589
05ef2f67 590=item EBCDIC
151b5d36 591
3ef515df 592The encoding pragma is not supported on EBCDIC platforms.
0ab8f81e
JH
593(Porters who are willing and able to remove this limitation are
594welcome.)
3ef515df 595
05ef2f67
JH
596=item format
597
598This pragma doesn't work well with format because PerlIO does not
599get along very well with it. When format contains non-ascii
600characters it prints funny or gets "wide character warnings".
601To understand it, try the code below.
602
603 # Save this one in utf8
604 # replace *non-ascii* with a non-ascii string
605 my $camel;
606 format STDOUT =
607 *non-ascii*@>>>>>>>
608 $camel
609 .
610 $camel = "*non-ascii*";
611 binmode(STDOUT=>':encoding(utf8)'); # bang!
612 write; # funny
613 print $camel, "\n"; # fine
614
615Without binmode this happens to work but without binmode, print()
616fails instead of write().
617
618At any rate, the very use of format is questionable when it comes to
619unicode characters since you have to consider such things as character
620width (i.e. double-width for ideographs) and directions (i.e. BIDI for
621Arabic and Hebrew).
622
151b5d36
JH
623=back
624
b1aeb384
JH
625=head2 The Logic of :locale
626
627The logic of C<:locale> is as follows:
628
629=over 4
630
631=item 1.
632
633If the platform supports the langinfo(CODESET) interface, the codeset
634returned is used as the default encoding for the open pragma.
635
636=item 2.
637
638If 1. didn't work but we are under the locale pragma, the environment
639variables LC_ALL and LANG (in that order) are matched for encodings
640(the part after C<.>, if any), and if any found, that is used
641as the default encoding for the open pragma.
642
643=item 3.
644
645If 1. and 2. didn't work, the environment variables LC_ALL and LANG
646(in that order) are matched for anything looking like UTF-8, and if
647any found, C<:utf8> is used as the default encoding for the open
648pragma.
649
650=back
651
652If your locale environment variables (LC_ALL, LC_CTYPE, LANG)
653contain the strings 'UTF-8' or 'UTF8' (case-insensitive matching),
654the default encoding of your STDIN, STDOUT, and STDERR, and of
655B<any subsequent file open>, is UTF-8.
656
05ef2f67
JH
657=head1 HISTORY
658
659This pragma first appeared in Perl 5.8.0. For features that require
6605.8.1 and better, see above.
661
b1aeb384
JH
662The C<:locale> subpragma was implemented in 2.01, or Perl 5.8.6.
663
3ef515df
JH
664=head1 SEE ALSO
665
aae85ceb
DK
666L<perlunicode>, L<Encode>, L<open>, L<Filter::Util::Call>,
667
668Ch. 15 of C<Programming Perl (3rd Edition)>
669by Larry Wall, Tom Christiansen, Jon Orwant;
670O'Reilly & Associates; ISBN 0-596-00027-8
3ef515df
JH
671
672=cut