10 Carp::croak "encoding pragma does not support EBCDIC platforms";
15 my ($class, $name) = @_;
16 $name = $ENV{PERL_ENCODING} if @_ < 2;
17 $name = "latin1" unless defined $name;
18 my $enc = find_encoding($name);
19 unless (defined $enc) {
21 Carp::croak "Unknown encoding '$name'";
30 encoding - pragma to control the conversion of legacy data into Unicode
34 use encoding "iso 8859-7";
36 # The \xDF of ISO 8859-7 (Greek) is \x{3af} in Unicode.
41 printf "%#x\n", ord($a); # will print 0x3af, not 0xdf
45 # $c will be "\x{3af}\x{100}", not "\x{df}\x{100}".
47 # chr() is affected, and ...
49 print "mega\n" if ord(chr(0xdf)) == 0x3af;
51 # ... ord() is affected by the encoding pragma ...
53 print "tera\n" if ord(pack("C", 0xdf)) == 0x3af;
55 # ... as are eq and cmp ...
57 print "peta\n" if "\x{3af}" eq pack("C", 0xdf);
58 print "exa\n" if "\x{3af}" cmp pack("C", 0xdf) == 0;
60 # ... but pack/unpack C are not affected, in case you still
61 # want back to your native encoding
63 print "zetta\n" if unpack("C", (pack("C", 0xdf))) == 0xdf;
67 Normally when legacy 8-bit data is converted to Unicode the data is
68 expected to be Latin-1 (or EBCDIC in EBCDIC platforms). With the
69 encoding pragma you can change this default.
71 The pragma is a per script, not a per block lexical. Only the last
72 C<use encoding> matters, and it affects B<the whole script>.
74 Notice that only literals (string or regular expression) having only
75 legacy code points are affected: if you mix data like this
79 the data is assumed to be in (Latin 1 and) Unicode, not in your native
80 encoding. In other words, this will match in "greek":
86 "\xDF\x{100}" =~ /\x{3af}\x{100}/
88 since the C<\xDF> on the left will B<not> be upgraded to C<\x{3af}>
89 because of the C<\x{100}> on the left. You should not be mixing your
90 legacy data and Unicode in the same string.
92 This pragma also affects encoding of the 0x80..0xFF code point range:
93 normally characters in that range are left as eight-bit bytes (unless
94 they are combined with characters with code points 0x100 or larger,
95 in which case all characters need to become UTF-8 encoded), but if
96 the C<encoding> pragma is present, even the 0x80..0xFF range always
99 If no encoding is specified, the environment variable L<PERL_ENCODING>
100 is consulted. If that fails, "latin1" (ISO 8859-1) is assumed. If no
101 encoding can be found, C<Unknown encoding '...'> error will be thrown.
103 =head1 KNOWN PROBLEMS
105 For native multibyte encodings (either fixed or variable length)
106 the current implementation of the regular expressions may introduce
107 recoding errors for longer regular expression literals than 127 bytes.
109 The encoding pragma is not supported on EBCDIC platforms.
113 L<perlunicode>, L<Encode>