Debian Codegraph @

upstream/debian-unstable/man3/ExtUtils::MakeMaker::Locale.3perl

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