Debian Codegraph @

upstream/mageia-cauldron/man3pm/ExtUtils::MakeMaker::Locale.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 "ExtUtils::MakeMaker::Locale 3pm"
61 .TH ExtUtils::MakeMaker::Locale 3pm 2025-06-24 "perl v5.42.0" "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 ExtUtils::MakeMaker::Locale \- bundled Encode::Locale
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& use Encode::Locale;
72 \& use Encode;
73 \&
74 \& $string = decode(locale => $bytes);
75 \& $bytes = encode(locale => $string);
76 \&
77 \& if (\-t) {
78 \& binmode(STDIN, ":encoding(console_in)");
79 \& binmode(STDOUT, ":encoding(console_out)");
80 \& binmode(STDERR, ":encoding(console_out)");
81 \& }
82 \&
83 \& # Processing file names passed in as arguments
84 \& my $uni_filename = decode(locale => $ARGV[0]);
85 \& open(my $fh, "<", encode(locale_fs => $uni_filename))
86 \& || die "Can\*(Aqt open \*(Aq$uni_filename\*(Aq: $!";
87 \& binmode($fh, ":encoding(locale)");
88 \& ...
89 .Ve
90 .SH DESCRIPTION
91 .IX Header "DESCRIPTION"
92 In many applications it\*(Aqs wise to let Perl use Unicode for the strings it
93 processes. Most of the interfaces Perl has to the outside world are still byte
94 based. Programs therefore need to decode byte strings that enter the program
95 from the outside and encode them again on the way out.
96 .PP
97 The POSIX locale system is used to specify both the language conventions
98 requested by the user and the preferred character set to consume and
99 output. The \f(CW\*(C`Encode::Locale\*(C'\fR module looks up the charset and encoding (called
100 a CODESET in the locale jargon) and arranges for the Encode module to know
101 this encoding under the name "locale". It means bytes obtained from the
102 environment can be converted to Unicode strings by calling \f(CW\*(C`Encode::encode(locale => $bytes)\*(C'\fR and converted back again with \f(CW\*(C`Encode::decode(locale => $string)\*(C'\fR.
103 .PP
104 Where file systems interfaces pass file names in and out of the program we also
105 need care. The trend is for operating systems to use a fixed file encoding
106 that don\*(Aqt actually depend on the locale; and this module determines the most
107 appropriate encoding for file names. The Encode module will know this
108 encoding under the name "locale_fs". For traditional Unix systems this will
109 be an alias to the same encoding as "locale".
110 .PP
111 For programs running in a terminal window (called a "Console" on some systems)
112 the "locale" encoding is usually a good choice for what to expect as input and
113 output. Some systems allows us to query the encoding set for the terminal and
114 \&\f(CW\*(C`Encode::Locale\*(C'\fR will do that if available and make these encodings known
115 under the \f(CW\*(C`Encode\*(C'\fR aliases "console_in" and "console_out". For systems where
116 we can\*(Aqt determine the terminal encoding these will be aliased as the same
117 encoding as "locale". The advice is to use "console_in" for input known to
118 come from the terminal and "console_out" for output to the terminal.
119 .PP
120 In addition to arranging for various Encode aliases the following functions and
121 variables are provided:
122 .IP "decode_argv( )" 4
123 .IX Item "decode_argv( )"
124 .PD 0
125 .IP "decode_argv( Encode::FB_CROAK )" 4
126 .IX Item "decode_argv( Encode::FB_CROAK )"
127 .PD
128 This will decode the command line arguments to perl (the \f(CW@ARGV\fR array) in\-place.
129 .Sp
130 The function will by default replace characters that can\*(Aqt be decoded by
131 "\ex{FFFD}", the Unicode replacement character.
132 .Sp
133 Any argument provided is passed as CHECK to underlying \fBEncode::decode()\fR call.
134 Pass the value \f(CW\*(C`Encode::FB_CROAK\*(C'\fR to have the decoding croak if not all the
135 command line arguments can be decoded. See "Handling Malformed Data" in Encode
136 for details on other options for CHECK.
137 .ie n .IP "env( $uni_key )" 4
138 .el .IP "env( \f(CW$uni_key\fR )" 4
139 .IX Item "env( $uni_key )"
140 .PD 0
141 .ie n .IP "env( $uni_key => $uni_value )" 4
142 .el .IP "env( \f(CW$uni_key\fR => \f(CW$uni_value\fR )" 4
143 .IX Item "env( $uni_key => $uni_value )"
144 .PD
145 Interface to get/set environment variables. Returns the current value as a
146 Unicode string. The \f(CW$uni_key\fR and \f(CW$uni_value\fR arguments are expected to be
147 Unicode strings as well. Passing \f(CW\*(C`undef\*(C'\fR as \f(CW$uni_value\fR deletes the
148 environment variable named \f(CW$uni_key\fR.
149 .Sp
150 The returned value will have the characters that can\*(Aqt be decoded replaced by
151 "\ex{FFFD}", the Unicode replacement character.
152 .Sp
153 There is no interface to request alternative CHECK behavior as for
154 \&\fBdecode_argv()\fR. If you need that you need to call encode/decode yourself.
155 For example:
156 .Sp
157 .Vb 2
158 \& my $key = Encode::encode(locale => $uni_key, Encode::FB_CROAK);
159 \& my $uni_value = Encode::decode(locale => $ENV{$key}, Encode::FB_CROAK);
160 .Ve
161 .IP "reinit( )" 4
162 .IX Item "reinit( )"
163 .PD 0
164 .ie n .IP "reinit( $encoding )" 4
165 .el .IP "reinit( \f(CW$encoding\fR )" 4
166 .IX Item "reinit( $encoding )"
167 .PD
168 Reinitialize the encodings from the locale. You want to call this function if
169 you changed anything in the environment that might influence the locale.
170 .Sp
171 This function will croak if the determined encoding isn\*(Aqt recognized by
172 the Encode module.
173 .Sp
174 With argument force \f(CW$ENCODING_\fR... variables to set to the given value.
175 .ie n .IP $ENCODING_LOCALE 4
176 .el .IP \f(CW$ENCODING_LOCALE\fR 4
177 .IX Item "$ENCODING_LOCALE"
178 The encoding name determined to be suitable for the current locale.
179 Encode know this encoding as "locale".
180 .ie n .IP $ENCODING_LOCALE_FS 4
181 .el .IP \f(CW$ENCODING_LOCALE_FS\fR 4
182 .IX Item "$ENCODING_LOCALE_FS"
183 The encoding name determined to be suitable for file system interfaces
184 involving file names.
185 Encode know this encoding as "locale_fs".
186 .ie n .IP $ENCODING_CONSOLE_IN 4
187 .el .IP \f(CW$ENCODING_CONSOLE_IN\fR 4
188 .IX Item "$ENCODING_CONSOLE_IN"
189 .PD 0
190 .ie n .IP $ENCODING_CONSOLE_OUT 4
191 .el .IP \f(CW$ENCODING_CONSOLE_OUT\fR 4
192 .IX Item "$ENCODING_CONSOLE_OUT"
193 .PD
194 The encodings to be used for reading and writing output to the a console.
195 Encode know these encodings as "console_in" and "console_out".
196 .SH NOTES
197 .IX Header "NOTES"
198 This table summarizes the mapping of the encodings set up
199 by the \f(CW\*(C`Encode::Locale\*(C'\fR module:
200 .PP
201 .Vb 7
202 \& Encode | | |
203 \& Alias | Windows | Mac OS X | POSIX
204 \& \-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-
205 \& locale | ANSI | nl_langinfo | nl_langinfo
206 \& locale_fs | ANSI | UTF\-8 | nl_langinfo
207 \& console_in | OEM | nl_langinfo | nl_langinfo
208 \& console_out | OEM | nl_langinfo | nl_langinfo
209 .Ve
210 .SS Windows
211 .IX Subsection "Windows"
212 Windows has basically 2 sets of APIs. A wide API (based on passing UTF\-16
213 strings) and a byte based API based a character set called ANSI. The
214 regular Perl interfaces to the OS currently only uses the ANSI APIs.
215 Unfortunately ANSI is not a single character set.
216 .PP
217 The encoding that corresponds to ANSI varies between different editions of
218 Windows. For many western editions of Windows ANSI corresponds to CP\-1252
219 which is a character set similar to ISO\-8859\-1. Conceptually the ANSI
220 character set is a similar concept to the POSIX locale CODESET so this module
221 figures out what the ANSI code page is and make this available as
222 \&\f(CW$ENCODING_LOCALE\fR and the "locale" Encoding alias.
223 .PP
224 Windows systems also operate with another byte based character set.
225 It\*(Aqs called the OEM code page. This is the encoding that the Console
226 takes as input and output. It\*(Aqs common for the OEM code page to
227 differ from the ANSI code page.
228 .SS "Mac OS X"
229 .IX Subsection "Mac OS X"
230 On Mac OS X the file system encoding is always UTF\-8 while the locale
231 can otherwise be set up as normal for POSIX systems.
232 .PP
233 File names on Mac OS X will at the OS\-level be converted to
234 NFD\-form. A file created by passing a NFC\-filename will come
235 in NFD\-form from \fBreaddir()\fR. See Unicode::Normalize for details
236 of NFD/NFC.
237 .PP
238 Actually, Apple does not follow the Unicode NFD standard since not all
239 character ranges are decomposed. The claim is that this avoids problems with
240 round trip conversions from old Mac text encodings. See Encode::UTF8Mac for
241 details.
242 .SS "POSIX (Linux and other Unixes)"
243 .IX Subsection "POSIX (Linux and other Unixes)"
244 File systems might vary in what encoding is to be used for
245 filenames. Since this module has no way to actually figure out
246 what the is correct it goes with the best guess which is to
247 assume filenames are encoding according to the current locale.
248 Users are advised to always specify UTF\-8 as the locale charset.
249 .SH "SEE ALSO"
250 .IX Header "SEE ALSO"
251 I18N::Langinfo, Encode, Term::Encoding
252 .SH AUTHOR
253 .IX Header "AUTHOR"
254 Copyright 2010 Gisle Aas <[email protected]>.
255 .PP
256 This library is free software; you can redistribute it and/or
257 modify it under the same terms as Perl itself.