Debian Codegraph @

upstream/opensuse-tumbleweed/man3/encoding.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "encoding 3pm"
61 .TH encoding 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 encoding \- allows you to write your script in non\-ASCII and non\-UTF\-8
68 .SH WARNING
69 .IX Header "WARNING"
70 This module has been deprecated since perl v5.18. See "DESCRIPTION" and
71 "BUGS".
72 .SH SYNOPSIS
73 .IX Header "SYNOPSIS"
74 .Vb 2
75 \& use encoding "greek"; # Perl like Greek to you?
76 \& use encoding "euc\-jp"; # Jperl!
77 \&
78 \& # or you can even do this if your shell supports your native encoding
79 \&
80 \& perl \-Mencoding=latin2 \-e\*(Aq...\*(Aq # Feeling centrally European?
81 \& perl \-Mencoding=euc\-kr \-e\*(Aq...\*(Aq # Or Korean?
82 \&
83 \& # more control
84 \&
85 \& # A simple euc\-cn => utf\-8 converter
86 \& use encoding "euc\-cn", STDOUT => "utf8"; while(<>){print};
87 \&
88 \& # "no encoding;" supported
89 \& no encoding;
90 \&
91 \& # an alternate way, Filter
92 \& use encoding "euc\-jp", Filter=>1;
93 \& # now you can use kanji identifiers \-\- in euc\-jp!
94 \&
95 \& # encode based on the current locale \- specialized purposes only;
96 \& # fraught with danger!!
97 \& use encoding \*(Aq:locale\*(Aq;
98 .Ve
99 .SH DESCRIPTION
100 .IX Header "DESCRIPTION"
101 This pragma is used to enable a Perl script to be written in encodings that
102 aren\*(Aqt strictly ASCII nor UTF\-8. It translates all or portions of the Perl
103 program script from a given encoding into UTF\-8, and changes the PerlIO layers
104 of \f(CW\*(C`STDIN\*(C'\fR and \f(CW\*(C`STDOUT\*(C'\fR to the encoding specified.
105 .PP
106 This pragma dates from the days when UTF\-8\-enabled editors were uncommon. But
107 that was long ago, and the need for it is greatly diminished. That, coupled
108 with the fact that it doesn\*(Aqt work with threads, along with other problems,
109 (see "BUGS") have led to its being deprecated. It is planned to remove this
110 pragma in a future Perl version. New code should be written in UTF\-8, and the
111 \&\f(CW\*(C`use utf8\*(C'\fR pragma used instead (see perluniintro and utf8 for details).
112 Old code should be converted to UTF\-8, via something like the recipe in the
113 "SYNOPSIS" (though this simple approach may require manual adjustments
114 afterwards).
115 .PP
116 If UTF\-8 is not an option, it is recommended that one use a simple source
117 filter, such as that provided by Filter::Encoding on CPAN or this
118 pragma\*(Aqs own \f(CW\*(C`Filter\*(C'\fR option (see below).
119 .PP
120 The only legitimate use of this pragma is almost certainly just one per file,
121 near the top, with file scope, as the file is likely going to only be written
122 in one encoding. Further restrictions apply in Perls before v5.22 (see
123 "Prior to Perl v5.22").
124 .PP
125 There are two basic modes of operation (plus turning if off):
126 .ie n .IP """use encoding [\*(Aq\fIENCNAME\fR\*(Aq] ;""" 4
127 .el .IP "\f(CWuse encoding [\*(Aq\fR\f(CIENCNAME\fR\f(CW\*(Aq] ;\fR" 4
128 .IX Item "use encoding ['ENCNAME'] ;"
129 Please note: This mode of operation is no longer supported as of Perl
130 v5.26.
131 .Sp
132 This is the normal operation. It translates various literals encountered in
133 the Perl source file from the encoding \fIENCNAME\fR into UTF\-8, and similarly
134 converts character code points. This is used when the script is a combination
135 of ASCII (for the variable names and punctuation, \fIetc\fR), but the literal
136 data is in the specified encoding.
137 .Sp
138 \&\fIENCNAME\fR is optional. If omitted, the encoding specified in the environment
139 variable \f(CW\*(C`PERL_ENCODING\*(C'\fR is used. If this isn\*(Aqt
140 set, or the resolved\-to encoding is not known to \f(CW\*(C`Encode\*(C'\fR, the error
141 \&\f(CW\*(C`Unknown encoding \*(Aq\fR\f(CIENCNAME\fR\f(CW\*(Aq\*(C'\fR will be thrown.
142 .Sp
143 Starting in Perl v5.8.6 (\f(CW\*(C`Encode\*(C'\fR version 2.0.1), \fIENCNAME\fR may be the
144 name \f(CW\*(C`:locale\*(C'\fR. This is for very specialized applications, and is documented
145 in "The \f(CW\*(C`:locale\*(C'\fR sub\-pragma" below.
146 .Sp
147 The literals that are converted are \f(CW\*(C`q//, qq//, qr//, qw///, qx//\*(C'\fR, and
148 starting in v5.8.1, \f(CW\*(C`tr///\*(C'\fR. Operations that do conversions include \f(CW\*(C`chr\*(C'\fR,
149 \&\f(CW\*(C`ord\*(C'\fR, \f(CW\*(C`utf8::upgrade\*(C'\fR (but not \f(CW\*(C`utf8::downgrade\*(C'\fR), and \f(CW\*(C`chomp\*(C'\fR.
150 .Sp
151 Also starting in v5.8.1, the \f(CW\*(C`DATA\*(C'\fR pseudo\-filehandle is translated from the
152 encoding into UTF\-8.
153 .Sp
154 For example, you can write code in EUC\-JP as follows:
155 .Sp
156 .Vb 3
157 \& my $Rakuda = "\exF1\exD1\exF1\exCC"; # Camel in Kanji
158 \& #<\-char\-><\-char\-> # 4 octets
159 \& s/\ebCamel\eb/$Rakuda/;
160 .Ve
161 .Sp
162 And with \f(CW\*(C`use encoding "euc\-jp"\*(C'\fR in effect, it is the same thing as
163 that code in UTF\-8:
164 .Sp
165 .Vb 2
166 \& my $Rakuda = "\ex{99F1}\ex{99DD}"; # two Unicode Characters
167 \& s/\ebCamel\eb/$Rakuda/;
168 .Ve
169 .Sp
170 See "EXAMPLE" below for a more complete example.
171 .Sp
172 Unless \f(CW\*(C`${^UNICODE}\*(C'\fR (available starting in v5.8.2) exists and is non\-zero, the
173 PerlIO layers of \f(CW\*(C`STDIN\*(C'\fR and \f(CW\*(C`STDOUT\*(C'\fR are set to "\f(CW:encoding(\fR\f(CIENCNAME\fR\f(CW)\fR".
174 Therefore,
175 .Sp
176 .Vb 5
177 \& use encoding "euc\-jp";
178 \& my $message = "Camel is the symbol of perl.\en";
179 \& my $Rakuda = "\exF1\exD1\exF1\exCC"; # Camel in Kanji
180 \& $message =~ s/\ebCamel\eb/$Rakuda/;
181 \& print $message;
182 .Ve
183 .Sp
184 will print
185 .Sp
186 .Vb 1
187 \& "\exF1\exD1\exF1\exCC is the symbol of perl.\en"
188 .Ve
189 .Sp
190 not
191 .Sp
192 .Vb 1
193 \& "\ex{99F1}\ex{99DD} is the symbol of perl.\en"
194 .Ve
195 .Sp
196 You can override this by giving extra arguments; see below.
197 .Sp
198 Note that \f(CW\*(C`STDERR\*(C'\fR WILL NOT be changed, regardless.
199 .Sp
200 Also note that non\-STD file handles remain unaffected. Use \f(CW\*(C`use
201 open\*(C'\fR or \f(CW\*(C`binmode\*(C'\fR to change the layers of those.
202 .ie n .IP """use encoding \fIENCNAME\fR, Filter=>1;""" 4
203 .el .IP "\f(CWuse encoding \fR\f(CIENCNAME\fR\f(CW, Filter=>1;\fR" 4
204 .IX Item "use encoding ENCNAME, Filter=>1;"
205 This operates as above, but the \f(CW\*(C`Filter\*(C'\fR argument with a non\-zero
206 value causes the entire script, and not just literals, to be translated from
207 the encoding into UTF\-8. This allows identifiers in the source to be in that
208 encoding as well. (Problems may occur if the encoding is not a superset of
209 ASCII; imagine all your semi\-colons being translated into something
210 different.) One can use this form to make
211 .Sp
212 .Vb 1
213 \& ${"\ex{4eba}"}++
214 .Ve
215 .Sp
216 work. (This is equivalent to \f(CW\*(C`$\fR\f(CIhuman\fR\f(CW++\*(C'\fR, where \fIhuman\fR is a single Han
217 ideograph).
218 .Sp
219 This effectively means that your source code behaves as if it were written in
220 UTF\-8 with \f(CW\*(C`\*(Aquse utf8\*(C'\fR\*(Aq in effect. So even if your editor only supports
221 Shift_JIS, for example, you can still try examples in Chapter 15 of
222 \&\f(CW\*(C`Programming Perl, 3rd Ed.\*(C'\fR.
223 .Sp
224 This option is significantly slower than the other one.
225 .ie n .IP """no encoding;""" 4
226 .el .IP "\f(CWno encoding;\fR" 4
227 .IX Item "no encoding;"
228 Unsets the script encoding. The layers of \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR are
229 reset to "\f(CW\*(C`:raw\*(C'\fR" (the default unprocessed raw stream of bytes).
230 .SH OPTIONS
231 .IX Header "OPTIONS"
232 .ie n .SS "Setting ""STDIN"" and/or ""STDOUT"" individually"
233 .el .SS "Setting \f(CWSTDIN\fP and/or \f(CWSTDOUT\fP individually"
234 .IX Subsection "Setting STDIN and/or STDOUT individually"
235 The encodings of \f(CW\*(C`STDIN\*(C'\fR and \f(CW\*(C`STDOUT\*(C'\fR are individually settable by parameters to
236 the pragma:
237 .PP
238 .Vb 1
239 \& use encoding \*(Aqeuc\-tw\*(Aq, STDIN => \*(Aqgreek\*(Aq ...;
240 .Ve
241 .PP
242 In this case, you cannot omit the first \fIENCNAME\fR. \f(CW\*(C`STDIN => undef\*(C'\fR
243 turns the I/O transcoding completely off for that filehandle.
244 .PP
245 When \f(CW\*(C`${^UNICODE}\*(C'\fR (available starting in v5.8.2) exists and is non\-zero,
246 these options will be completely ignored. See "\f(CW\*(C`${^UNICODE}\*(C'\fR" in perlvar and
247 "\f(CW\*(C`\-C\*(C'\fR" in perlrun for details.
248 .ie n .SS "The "":locale"" sub\-pragma"
249 .el .SS "The \f(CW:locale\fP sub\-pragma"
250 .IX Subsection "The :locale sub-pragma"
251 Starting in v5.8.6, the encoding name may be \f(CW\*(C`:locale\*(C'\fR. This means that the
252 encoding is taken from the current locale, and not hard\-coded by the pragma.
253 Since a script really can only be encoded in exactly one encoding, this option
254 is dangerous. It makes sense only if the script itself is written in ASCII,
255 and all the possible locales that will be in use when the script is executed
256 are supersets of ASCII. That means that the script itself doesn\*(Aqt get
257 changed, but the I/O handles have the specified encoding added, and the
258 operations like \f(CW\*(C`chr\*(C'\fR and \f(CW\*(C`ord\*(C'\fR use that encoding.
259 .PP
260 The logic of finding which locale \f(CW\*(C`:locale\*(C'\fR uses is as follows:
261 .IP 1. 4
262 If the platform supports the \f(CWlanginfo(CODESET)\fR interface, the codeset
263 returned is used as the default encoding for the open pragma.
264 .IP 2. 4
265 If 1. didn\*(Aqt work but we are under the locale pragma, the environment
266 variables \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LANG\*(C'\fR (in that order) are matched for encodings
267 (the part after "\f(CW\*(C`.\*(C'\fR", if any), and if any found, that is used
268 as the default encoding for the open pragma.
269 .IP 3. 4
270 If 1. and 2. didn\*(Aqt work, the environment variables \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LANG\*(C'\fR
271 (in that order) are matched for anything looking like UTF\-8, and if
272 any found, \f(CW\*(C`:utf8\*(C'\fR is used as the default encoding for the open
273 pragma.
274 .PP
275 If your locale environment variables (\f(CW\*(C`LC_ALL\*(C'\fR, \f(CW\*(C`LC_CTYPE\*(C'\fR, \f(CW\*(C`LANG\*(C'\fR)
276 contain the strings \*(AqUTF\-8\*(Aq or \*(AqUTF8\*(Aq (case\-insensitive matching),
277 the default encoding of your \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR, and \f(CW\*(C`STDERR\*(C'\fR, and of
278 \&\fBany subsequent file open\fR, is UTF\-8.
279 .SH CAVEATS
280 .IX Header "CAVEATS"
281 .SS "SIDE EFFECTS"
282 .IX Subsection "SIDE EFFECTS"
283 .IP \(bu 4
284 If the \f(CW\*(C`encoding\*(C'\fR pragma is in scope then the lengths returned are
285 calculated from the length of \f(CW$/\fR in Unicode characters, which is not
286 always the same as the length of \f(CW$/\fR in the native encoding.
287 .IP \(bu 4
288 Without this pragma, if strings operating under byte semantics and strings
289 with Unicode character data are concatenated, the new string will
290 be created by decoding the byte strings as \fIISO 8859\-1 (Latin\-1)\fR.
291 .Sp
292 The \fBencoding\fR pragma changes this to use the specified encoding
293 instead. For example:
294 .Sp
295 .Vb 5
296 \& use encoding \*(Aqutf8\*(Aq;
297 \& my $string = chr(20000); # a Unicode string
298 \& utf8::encode($string); # now it\*(Aqs a UTF\-8 encoded byte string
299 \& # concatenate with another Unicode string
300 \& print length($string . chr(20000));
301 .Ve
302 .Sp
303 Will print \f(CW2\fR, because \f(CW$string\fR is upgraded as UTF\-8. Without
304 \&\f(CW\*(C`use encoding \*(Aqutf8\*(Aq;\*(C'\fR, it will print \f(CW4\fR instead, since \f(CW$string\fR
305 is three octets when interpreted as Latin\-1.
306 .SS "DO NOT MIX MULTIPLE ENCODINGS"
307 .IX Subsection "DO NOT MIX MULTIPLE ENCODINGS"
308 Notice that only literals (string or regular expression) having only
309 legacy code points are affected: if you mix data like this
310 .PP
311 .Vb 2
312 \& \ex{100}\exDF
313 \& \exDF\ex{100}
314 .Ve
315 .PP
316 the data is assumed to be in (Latin 1 and) Unicode, not in your native
317 encoding. In other words, this will match in "greek":
318 .PP
319 .Vb 1
320 \& "\exDF" =~ /\ex{3af}/
321 .Ve
322 .PP
323 but this will not
324 .PP
325 .Vb 1
326 \& "\exDF\ex{100}" =~ /\ex{3af}\ex{100}/
327 .Ve
328 .PP
329 since the \f(CW\*(C`\exDF\*(C'\fR (ISO 8859\-7 GREEK SMALL LETTER IOTA WITH TONOS) on
330 the left will \fBnot\fR be upgraded to \f(CW\*(C`\ex{3af}\*(C'\fR (Unicode GREEK SMALL
331 LETTER IOTA WITH TONOS) because of the \f(CW\*(C`\ex{100}\*(C'\fR on the left. You
332 should not be mixing your legacy data and Unicode in the same string.
333 .PP
334 This pragma also affects encoding of the 0x80..0xFF code point range:
335 normally characters in that range are left as eight\-bit bytes (unless
336 they are combined with characters with code points 0x100 or larger,
337 in which case all characters need to become UTF\-8 encoded), but if
338 the \f(CW\*(C`encoding\*(C'\fR pragma is present, even the 0x80..0xFF range always
339 gets UTF\-8 encoded.
340 .PP
341 After all, the best thing about this pragma is that you don\*(Aqt have to
342 resort to \ex{....} just to spell your name in a native encoding.
343 So feel free to put your strings in your encoding in quotes and
344 regexes.
345 .SS "Prior to Perl v5.22"
346 .IX Subsection "Prior to Perl v5.22"
347 The pragma was a per script, not a per block lexical. Only the last
348 \&\f(CW\*(C`use encoding\*(C'\fR or \f(CW\*(C`no encoding\*(C'\fR mattered, and it affected
349 \&\fBthe whole script\fR. However, the \f(CW\*(C`no encoding\*(C'\fR pragma was supported and
350 \&\f(CW\*(C`use encoding\*(C'\fR could appear as many times as you want in a given script
351 (though only the last was effective).
352 .PP
353 Since the scope wasn\*(Aqt lexical, other modules\*(Aq use of \f(CW\*(C`chr\*(C'\fR, \f(CW\*(C`ord\*(C'\fR, \fIetc.\fR
354 were affected. This leads to spooky, incorrect action at a distance that is
355 hard to debug.
356 .PP
357 This means you would have to be very careful of the load order:
358 .PP
359 .Vb 5
360 \& # called module
361 \& package Module_IN_BAR;
362 \& use encoding "bar";
363 \& # stuff in "bar" encoding here
364 \& 1;
365 \&
366 \& # caller script
367 \& use encoding "foo"
368 \& use Module_IN_BAR;
369 \& # surprise! use encoding "bar" is in effect.
370 .Ve
371 .PP
372 The best way to avoid this oddity is to use this pragma RIGHT AFTER
373 other modules are loaded. i.e.
374 .PP
375 .Vb 2
376 \& use Module_IN_BAR;
377 \& use encoding "foo";
378 .Ve
379 .SS "Prior to Encode version 1.87"
380 .IX Subsection "Prior to Encode version 1.87"
381 .IP \(bu 4
382 \&\f(CW\*(C`STDIN\*(C'\fR and \f(CW\*(C`STDOUT\*(C'\fR were not set under the filter option.
383 And \f(CW\*(C`STDIN=>\fR\f(CIENCODING\fR\f(CW\*(C'\fR and \f(CW\*(C`STDOUT=>\fR\f(CIENCODING\fR\f(CW\*(C'\fR didn\*(Aqt work like
384 non\-filter version.
385 .IP \(bu 4
386 \&\f(CW\*(C`use utf8\*(C'\fR wasn\*(Aqt implicitly declared so you have to \f(CW\*(C`use utf8\*(C'\fR to do
387 .Sp
388 .Vb 1
389 \& ${"\ex{4eba}"}++
390 .Ve
391 .SS "Prior to Perl v5.8.1"
392 .IX Subsection "Prior to Perl v5.8.1"
393 .IP """NON\-EUC"" doublebyte encodings" 4
394 .IX Item """NON-EUC"" doublebyte encodings"
395 Because perl needs to parse the script before applying this pragma, such
396 encodings as Shift_JIS and Big\-5 that may contain \f(CW\*(Aq\e\*(Aq\fR (BACKSLASH;
397 \&\f(CW\*(C`\ex5c\*(C'\fR) in the second byte fail because the second byte may
398 accidentally escape the quoting character that follows.
399 .ie n .IP """tr///""" 4
400 .el .IP \f(CWtr///\fR 4
401 .IX Item "tr///"
402 The \fBencoding\fR pragma works by decoding string literals in
403 \&\f(CW\*(C`q//,qq//,qr//,qw///, qx//\*(C'\fR and so forth. In perl v5.8.0, this
404 does not apply to \f(CW\*(C`tr///\*(C'\fR. Therefore,
405 .Sp
406 .Vb 4
407 \& use encoding \*(Aqeuc\-jp\*(Aq;
408 \& #....
409 \& $kana =~ tr/\exA4\exA1\-\exA4\exF3/\exA5\exA1\-\exA5\exF3/;
410 \& # \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-
411 .Ve
412 .Sp
413 Does not work as
414 .Sp
415 .Vb 1
416 \& $kana =~ tr/\ex{3041}\-\ex{3093}/\ex{30a1}\-\ex{30f3}/;
417 .Ve
418 .RS 4
419 .IP "Legend of characters above" 4
420 .IX Item "Legend of characters above"
421 .Vb 6
422 \& utf8 euc\-jp charnames::viacode()
423 \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
424 \& \ex{3041} \exA4\exA1 HIRAGANA LETTER SMALL A
425 \& \ex{3093} \exA4\exF3 HIRAGANA LETTER N
426 \& \ex{30a1} \exA5\exA1 KATAKANA LETTER SMALL A
427 \& \ex{30f3} \exA5\exF3 KATAKANA LETTER N
428 .Ve
429 .RE
430 .RS 4
431 .Sp
432 This counterintuitive behavior has been fixed in perl v5.8.1.
433 .Sp
434 In perl v5.8.0, you can work around this as follows;
435 .Sp
436 .Vb 3
437 \& use encoding \*(Aqeuc\-jp\*(Aq;
438 \& # ....
439 \& eval qq{ \e$kana =~ tr/\exA4\exA1\-\exA4\exF3/\exA5\exA1\-\exA5\exF3/ };
440 .Ve
441 .Sp
442 Note the \f(CW\*(C`tr//\*(C'\fR expression is surrounded by \f(CW\*(C`qq{}\*(C'\fR. The idea behind
443 this is the same as the classic idiom that makes \f(CW\*(C`tr///\*(C'\fR \*(Aqinterpolate\*(Aq:
444 .Sp
445 .Vb 2
446 \& tr/$from/$to/; # wrong!
447 \& eval qq{ tr/$from/$to/ }; # workaround.
448 .Ve
449 .RE
450 .SH "EXAMPLE \- Greekperl"
451 .IX Header "EXAMPLE - Greekperl"
452 .Vb 1
453 \& use encoding "iso 8859\-7";
454 \&
455 \& # \exDF in ISO 8859\-7 (Greek) is \ex{3af} in Unicode.
456 \&
457 \& $a = "\exDF";
458 \& $b = "\ex{100}";
459 \&
460 \& printf "%#x\en", ord($a); # will print 0x3af, not 0xdf
461 \&
462 \& $c = $a . $b;
463 \&
464 \& # $c will be "\ex{3af}\ex{100}", not "\ex{df}\ex{100}".
465 \&
466 \& # chr() is affected, and ...
467 \&
468 \& print "mega\en" if ord(chr(0xdf)) == 0x3af;
469 \&
470 \& # ... ord() is affected by the encoding pragma ...
471 \&
472 \& print "tera\en" if ord(pack("C", 0xdf)) == 0x3af;
473 \&
474 \& # ... as are eq and cmp ...
475 \&
476 \& print "peta\en" if "\ex{3af}" eq pack("C", 0xdf);
477 \& print "exa\en" if "\ex{3af}" cmp pack("C", 0xdf) == 0;
478 \&
479 \& # ... but pack/unpack C are not affected, in case you still
480 \& # want to go back to your native encoding
481 \&
482 \& print "zetta\en" if unpack("C", (pack("C", 0xdf))) == 0xdf;
483 .Ve
484 .SH BUGS
485 .IX Header "BUGS"
486 .IP "Thread safety" 4
487 .IX Item "Thread safety"
488 \&\f(CW\*(C`use encoding ...\*(C'\fR is not thread\-safe (i.e., do not use in threaded
489 applications).
490 .IP "Can\*(Aqt be used by more than one module in a single program." 4
491 .IX Item "Can't be used by more than one module in a single program."
492 Only one encoding is allowed. If you combine modules in a program that have
493 different encodings, only one will be actually used.
494 .ie n .IP "Other modules using ""STDIN"" and ""STDOUT"" get the encoded stream" 4
495 .el .IP "Other modules using \f(CWSTDIN\fR and \f(CWSTDOUT\fR get the encoded stream" 4
496 .IX Item "Other modules using STDIN and STDOUT get the encoded stream"
497 They may be expecting something completely different.
498 .IP "literals in regex that are longer than 127 bytes" 4
499 .IX Item "literals in regex that are longer than 127 bytes"
500 For native multibyte encodings (either fixed or variable length),
501 the current implementation of the regular expressions may introduce
502 recoding errors for regular expression literals longer than 127 bytes.
503 .IP EBCDIC 4
504 .IX Item "EBCDIC"
505 The encoding pragma is not supported on EBCDIC platforms.
506 .ie n .IP """format""" 4
507 .el .IP \f(CWformat\fR 4
508 .IX Item "format"
509 This pragma doesn\*(Aqt work well with \f(CW\*(C`format\*(C'\fR because PerlIO does not
510 get along very well with it. When \f(CW\*(C`format\*(C'\fR contains non\-ASCII
511 characters it prints funny or gets "wide character warnings".
512 To understand it, try the code below.
513 .Sp
514 .Vb 11
515 \& # Save this one in utf8
516 \& # replace *non\-ascii* with a non\-ascii string
517 \& my $camel;
518 \& format STDOUT =
519 \& *non\-ascii*@>>>>>>>
520 \& $camel
521 \& .
522 \& $camel = "*non\-ascii*";
523 \& binmode(STDOUT=>\*(Aq:encoding(utf8)\*(Aq); # bang!
524 \& write; # funny
525 \& print $camel, "\en"; # fine
526 .Ve
527 .Sp
528 Without binmode this happens to work but without binmode, \fBprint()\fR
529 fails instead of \fBwrite()\fR.
530 .Sp
531 At any rate, the very use of \f(CW\*(C`format\*(C'\fR is questionable when it comes to
532 unicode characters since you have to consider such things as character
533 width (i.e. double\-width for ideographs) and directions (i.e. BIDI for
534 Arabic and Hebrew).
535 .IP "See also ""CAVEATS""" 4
536 .IX Item "See also ""CAVEATS"""
537 .SH HISTORY
538 .IX Header "HISTORY"
539 This pragma first appeared in Perl v5.8.0. It has been enhanced in later
540 releases as specified above.
541 .SH "SEE ALSO"
542 .IX Header "SEE ALSO"
543 perlunicode, Encode, open, Filter::Util::Call,
544 .PP
545 Ch. 15 of \f(CW\*(C`Programming Perl (3rd Edition)\*(C'\fR
546 by Larry Wall, Tom Christiansen, Jon Orwant;
547 O\*(AqReilly & Associates; ISBN 0\-596\-00027\-8