X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperllocale.pod;h=3c2b3ab8ae2b4b2cc4b698343e93b39a0278c4c4;hb=3c295041e5d570578f09b8e99de0a179cc172164;hp=dba15feffebbd9954c4b7f881abc30b720cea01a;hpb=b687b08b628449b317ff558f31d9d716ace045de;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perllocale.pod b/pod/perllocale.pod index dba15fe..3c2b3ab 100644 --- a/pod/perllocale.pod +++ b/pod/perllocale.pod @@ -99,11 +99,11 @@ C. sort() is also affected if used without an explicit comparison function, because it uses C by default. B C and C are unaffected by locale: they always -perform a byte-by-byte comparison of their scalar operands. What's +perform a char-by-char comparison of their scalar operands. What's more, if C finds that its operands are equal according to the collation sequence specified by the current locale, it goes on to -perform a byte-by-byte comparison, and only returns I<0> (equal) if the -operands are bit-for-bit identical. If you really want to know whether +perform a char-by-char comparison, and only returns I<0> (equal) if the +operands are char-for-char identical. If you really want to know whether two strings--which C and C may consider different--are equal as far as collation in the locale is concerned, see the discussion in L. @@ -124,8 +124,8 @@ B (strftime()) uses C. =back -C, C, and so on, are discussed further in L. +C, C, and so on, are discussed further in +L. The default behavior is restored with the S> pragma, or upon reaching the end of block enclosing C. @@ -177,7 +177,7 @@ subsequent call to setlocale(). If no second argument is provided and the category is LC_ALL, the result is implementation-dependent. It may be a string of concatenated locales names (separator also implementation-dependent) -or a single locale name. Please consult your L for +or a single locale name. Please consult your setlocale(3) man page for details. If a second argument is given and it corresponds to a valid locale, @@ -197,11 +197,11 @@ be noticed, depending on your system's C library. If the second argument does not correspond to a valid locale, the locale for the category is not changed, and the function returns I. -For further information about the categories, consult L. +For further information about the categories, consult setlocale(3). =head2 Finding locales -For locales available in your system, consult also L to +For locales available in your system, consult also setlocale(3) to see whether it leads to the list of available locales (search for the I section). If that fails, try the following command lines: @@ -215,6 +215,8 @@ I section). If that fails, try the following command lines: ls /usr/lib/nls + ls /usr/share/locale + and see whether they list something resembling these en_US.ISO8859-1 de_DE.ISO8859-1 ru_RU.ISO8859-5 @@ -225,18 +227,18 @@ and see whether they list something resembling these english.iso88591 german.iso88591 russian.iso88595 english.roman8 russian.koi8r -Sadly, even though the calling interface for setlocale() has -been standardized, names of locales and the directories where the +Sadly, even though the calling interface for setlocale() has been +standardized, names of locales and the directories where the configuration resides have not been. The basic form of the name is -IB<.>I, but the latter parts after -I are not always present. The I and I are -usually from the standards B and B, the two-letter -abbreviations for the countries and the languages of the world, -respectively. The I part often mentions some B -character set, the Latin codesets. For example, C is the -so-called "Western codeset" that can be used to encode most Western -European languages. Again, there are several ways to write even the -name of that one standard. Lamentably. +IB<.>I, but the latter parts after +I are not always present. The I and I +are usually from the standards B and B, the +two-letter abbreviations for the countries and the languages of the +world, respectively. The I part often mentions some B character set, the Latin codesets. For example, C +is the so-called "Western European codeset" that can be used to encode +most Western European languages adequately. Again, there are several +ways to write even the name of that one standard. Lamentably. Two special locales are worth particular mention: "C" and "POSIX". Currently these are effectively the same locale: the difference is @@ -287,11 +289,11 @@ than the PERL_BADLANG approach, but setting LC_ALL (or other locale variables) may affect other programs as well, not just Perl. In particular, external programs run from within Perl will see these changes. If you make the new settings permanent (read on), all -programs you run see the changes. See L for for +programs you run see the changes. See L<"ENVIRONMENT"> for the full list of relevant environment variables and L for their effects in Perl. Effects in other programs are easily deducible. For example, the variable LC_COLLATE may well affect -your B program (or whatever the program that arranges `records' +your B program (or whatever the program that arranges "records" alphabetically in your system is called). You can test out changing these variables temporarily, and if the @@ -307,7 +309,11 @@ discussed above. We decided to try that instead of the above faulty locale "En_US"--and in Cshish shells (B, B) setenv LC_ALL en_US.ISO8859-1 - + +or if you have the "env" application you can do in any shell + + env LC_ALL=en_US.ISO8859-1 perl ... + If you do not know what shell you have, consult your local helpdesk or the equivalent. @@ -330,9 +336,9 @@ Second, if using the listed commands you see something B (prefix matches do not count and case usually counts) like "En_US" without the quotes, then you should be okay because you are using a locale name that should be installed and available in your system. -In this case, see L. +In this case, see L. -=head2 Permanently fixing your locale configuration +=head2 Permanently fixing your system's locale configuration This is when you see something like: @@ -346,8 +352,8 @@ commands. You may see things like "en_US.ISO8859-1", but that isn't the same. In this case, try running under a locale that you can list and which somehow matches what you tried. The rules for matching locale names are a bit vague because -standardization is weak in this area. See again the L about general rules. +standardization is weak in this area. See again the +L about general rules. =head2 Fixing system locale configuration @@ -379,7 +385,7 @@ with a single parameter--see L.) localeconv() takes no arguments, and returns B a hash. The keys of this hash are variable names for formatting, such as C and C. The values are the -corresponding, er, values. See L for a longer +corresponding, er, values. See L for a longer example listing the categories an implementation might be expected to provide; some provide more and others fewer. You don't need an explicit C, because localeconv() always observes the @@ -425,6 +431,31 @@ parameters as integers correctly formatted in the current locale: } print "\n"; +=head2 I18N::Langinfo + +Another interface for querying locale-dependent information is the +I18N::Langinfo::langinfo() function, available at least in UNIX-like +systems and VMS. + +The following example will import the langinfo() function itself and +three constants to be used as arguments to langinfo(): a constant for +the abbreviated first day of the week (the numbering starts from +Sunday = 1) and two more constants for the affirmative and negative +answers for a yes/no question in the current locale. + + use I18N::Langinfo qw(langinfo ABDAY_1 YESSTR NOSTR); + + my ($abday_1, $yesstr, $nostr) = map { langinfo } qw(ABDAY_1 YESSTR NOSTR); + + print "$abday_1? [$yesstr/$nostr] "; + +In other words, in the "C" (or English) locale the above will probably +print something like: + + Sun? [yes/no] + +See L for more information. + =head1 LOCALE CATEGORIES The following subsections describe basic locale categories. Beyond these, @@ -443,21 +474,21 @@ The following collations all make sense and you may meet any of them if you "use locale". A B C D E a b c d e - A a B b C c D d D e + A a B b C c D d E e a A b B c C d D e E a b c d e A B C D E -Here is a code snippet to tell what alphanumeric +Here is a code snippet to tell what "word" characters are in the current locale, in that locale's order: use locale; - print +(sort grep /\w/, map { chr() } 0..255), "\n"; + print +(sort grep /\w/, map { chr } 0..255), "\n"; Compare this with the characters that you see and their order if you state explicitly that the locale should be ignored: no locale; - print +(sort grep /\w/, map { chr() } 0..255), "\n"; + print +(sort grep /\w/, map { chr } 0..255), "\n"; This machine-native collation (which is what you get unless S> has appeared earlier in the same block) must be used for @@ -466,7 +497,7 @@ first example is useful for natural text. As noted in L, C compares according to the current collation locale when C is in effect, but falls back to a -byte-by-byte comparison for strings that the locale says are equal. You +char-by-char comparison for strings that the locale says are equal. You can use POSIX::strcoll() if you don't want this fall-back: use POSIX qw(strcoll); @@ -491,9 +522,9 @@ efficiency by using POSIX::strxfrm() in conjunction with C: if $xfrm_string eq strxfrm("mixed-case string"); strxfrm() takes a string and maps it into a transformed string for use -in byte-by-byte comparisons against other transformed strings during +in char-by-char comparisons against other transformed strings during collation. "Under the hood", locale-affected Perl comparison operators -call strxfrm() for both operands, then do a byte-by-byte +call strxfrm() for both operands, then do a char-by-char comparison of the transformed strings. By calling strxfrm() explicitly and using a non locale-affected comparison, the example attempts to save a couple of transformations. But in fact, it doesn't save anything: Perl @@ -516,8 +547,9 @@ results, and so always obey the current C locale. In the scope of S>, Perl obeys the C locale setting. This controls the application's notion of which characters are alphabetic. This affects Perl's C<\w> regular expression metanotation, -which stands for alphanumeric characters--that is, alphabetic and -numeric characters. (Consult L for more information about +which stands for alphanumeric characters--that is, alphabetic, +numeric, and including other special characters such as the underscore or +hyphen. (Consult L for more information about regular expressions.) Thanks to C, depending on your locale setting, characters like 'E', 'E', 'E', and 'E' may be understood as C<\w> characters. @@ -542,46 +574,51 @@ should use C<\w> inside a C block. See L<"SECURITY">. =head2 Category LC_NUMERIC: Numeric Formatting -In the scope of S>, Perl obeys the C locale -information, which controls an application's idea of how numbers should -be formatted for human readability by the printf(), sprintf(), and -write() functions. String-to-numeric conversion by the POSIX::strtod() +After a proper POSIX::setlocale() call, Perl obeys the C +locale information, which controls an application's idea of how numbers +should be formatted for human readability by the printf(), sprintf(), and +write() functions. String-to-numeric conversion by the POSIX::strtod() function is also affected. In most implementations the only effect is to change the character used for the decimal point--perhaps from '.' to ','. These functions aren't aware of such niceties as thousands separation and -so on. (See L if you care about these things.) +so on. (See L if you care about these things.) -Output produced by print() is B affected by the -current locale: it is independent of whether C or C is in effect, and corresponds to what you'd get from printf() -in the "C" locale. The same is true for Perl's internal conversions -between numeric and string formats: +Output produced by print() is also affected by the current locale: it +corresponds to what you'd get from printf() in the "C" locale. The +same is true for Perl's internal conversions between numeric and +string formats: - use POSIX qw(strtod); - use locale; + use POSIX qw(strtod setlocale LC_NUMERIC); + + setlocale LC_NUMERIC, ""; $n = 5/2; # Assign numeric 2.5 to $n - $a = " $n"; # Locale-independent conversion to string + $a = " $n"; # Locale-dependent conversion to string - print "half five is $n\n"; # Locale-independent output + print "half five is $n\n"; # Locale-dependent output printf "half five is %g\n", $n; # Locale-dependent output print "DECIMAL POINT IS COMMA\n" if $n == (strtod("2,5"))[0]; # Locale-dependent conversion +See also L and C. + =head2 Category LC_MONETARY: Formatting of monetary amounts The C standard defines the C category, but no function that is affected by its contents. (Those with experience of standards committees will recognize that the working group decided to punt on the issue.) Consequently, Perl takes no notice of it. If you really want -to use C, you can query its contents--see L--and use the information that it returns in your application's -own formatting of currency amounts. However, you may well find that -the information, voluminous and complex though it may be, still does not -quite meet your requirements: currency formatting is a hard nut to crack. +to use C, you can query its contents--see +L--and use the information that it returns in your +application's own formatting of currency amounts. However, you may well +find that the information, voluminous and complex though it may be, still +does not quite meet your requirements: currency formatting is a hard nut +to crack. + +See also L and C. =head2 LC_TIME @@ -602,12 +639,19 @@ Note: C isn't needed in this example: as a function that exists only to generate locale-dependent results, strftime() always obeys the current C locale. +See also L and C..C, C..C, +C..C, and C..C. + =head2 Other categories The remaining locale category, C (possibly supplemented by others in particular implementations) is not currently used by -Perl--except possibly to affect the behavior of library functions called -by extensions outside the standard Perl distribution. +Perl--except possibly to affect the behavior of library functions +called by extensions outside the standard Perl distribution and by the +operating system and its utilities. Note especially that the string +value of C<$!> and the error messages given by external utilities may +be changed by C. If you want to have portable error +codes, use C<%!>. See L. =head1 SECURITY @@ -635,14 +679,6 @@ case-mapping table is in effect. =item * -If the decimal point character in the C locale is -surreptitiously changed from a dot to a comma, C produces a string result of "123,456". Many people would -interpret this as one hundred and twenty-three thousand, four hundred -and fifty-six. - -=item * - A sneaky C locale could result in the names of students with "D" grades appearing ahead of those with "A"s. @@ -678,29 +714,37 @@ the locale: =over 4 -=item B (C, C, C, C and C): +=item * + +B (C, C, C, C and C): Scalar true/false (or less/equal/greater) result is never tainted. -=item B (with C<\l>, C<\L>, C<\u> or C<\U>) +=item * + +B (with C<\l>, C<\L>, C<\u> or C<\U>) Result string containing interpolated material is tainted if C is in effect. -=item B (C): +=item * + +B (C): Scalar true/false result never tainted. Subpatterns, either delivered as a list-context result or as $1 etc. are tainted if C is in effect, and the subpattern regular expression contains C<\w> (to match an alphanumeric character), C<\W> -(non-alphanumeric character), C<\s> (white-space character), or C<\S> -(non white-space character). The matched-pattern variable, $&, $` +(non-alphanumeric character), C<\s> (whitespace character), or C<\S> +(non whitespace character). The matched-pattern variable, $&, $` (pre-match), $' (post-match), and $+ (last match) are also tainted if C is in effect and the regular expression contains C<\w>, C<\W>, C<\s>, or C<\S>. -=item B (C): +=item * + +B (C): Has the same behavior as the match operator. Also, the left operand of C<=~> becomes tainted when C in effect @@ -708,24 +752,30 @@ if modified as a result of a substitution based on a regular expression match involving C<\w>, C<\W>, C<\s>, or C<\S>; or of case-mapping with C<\l>, C<\L>,C<\u> or C<\U>. -=item B (sprintf()): +=item * -Result is tainted if C is in effect. +B (printf() and write()): -=item B (printf() and write()): +Results are never tainted because otherwise even output from print, +for example C, should be tainted if C is in +effect. -Success/failure result is never tainted. +=item * -=item B (lc(), lcfirst(), uc(), ucfirst()): +B (lc(), lcfirst(), uc(), ucfirst()): Results are tainted if C is in effect. -=item B (localeconv(), strcoll(), +=item * + +B (localeconv(), strcoll(), strftime(), strxfrm()): Results are never tainted. -=item B (isalnum(), isalpha(), isdigit(), +=item * + +B (isalnum(), isalpha(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()): @@ -807,6 +857,20 @@ for controlling an application's opinion on data. C is the "override-all" locale environment variable. If set, it overrides all the rest of the locale environment variables. +=item LANGUAGE + +B: C is a GNU extension, it affects you only if you +are using the GNU libc. This is the case if you are using e.g. Linux. +If you are using "commercial" UNIXes you are most probably I +using GNU libc and you can ignore C. + +However, in the case you are using C: it affects the +language of informational, warning, and error messages output by +commands (in other words, it's like C) but it has higher +priority than L. Moreover, it's not a single value but +instead a "path" (":"-separated list) of I (not locales). +See the GNU C library documentation for more information. + =item LC_CTYPE In the absence of C, C chooses the character type @@ -845,6 +909,23 @@ category-specific C. =back +=head2 Examples + +The LC_NUMERIC controls the numeric output: + + use locale; + use POSIX qw(locale_h); # Imports setlocale() and the LC_ constants. + setlocale(LC_NUMERIC, "fr_FR") or die "Pardon"; + printf "%g\n", 1.23; # If the "fr_FR" succeeded, probably shows 1,23. + +and also how strings are parsed by POSIX::strtod() as numbers: + + use locale; + use POSIX qw(locale_h strtod); + setlocale(LC_NUMERIC, "de_DE") or die "Entschuldigung"; + my $x = strtod("2,34") + 5; + print $x, "\n"; # Probably shows 7,34. + =head1 NOTES =head2 Backward compatibility @@ -897,7 +978,7 @@ structure. =head2 Freely available locale definitions There is a large collection of locale definitions at -C. You should be aware that it is +ftp://dkuug.dk/i18n/WG15-collection . You should be aware that it is unsupported, and is not claimed to be fit for any purpose. If your system allows installation of arbitrary locales, you may find the definitions useful as they are, or as a basis for the development of @@ -921,6 +1002,15 @@ nations, when we all know that the world can equally well be divided into bankers, bikers, gamers, and so on. But, for now, it's the only standard we've got. This may be construed as a bug. +=head1 Unicode and UTF-8 + +The support of Unicode is new starting from Perl version 5.6, and +more fully implemented in the version 5.8. See L and +L for more details. + +Usually locale settings and Unicode do not affect each other, but +there are exceptions, see L for examples. + =head1 BUGS =head2 Broken systems @@ -929,44 +1019,20 @@ In certain systems, the operating system's locale support is broken and cannot be fixed or used by Perl. Such deficiencies can and will result in mysterious hangs and/or Perl core dumps when the C is in effect. When confronted with such a system, -please report in excruciating detail to >, and +please report in excruciating detail to >, and complain to your vendor: bug fixes may exist for these problems in your operating system. Sometimes such bug fixes are called an operating system upgrade. =head1 SEE ALSO -L - -L - -L - -L - -L - -L, - -L - -L - -L, - -L - -L - -L, - -L - -L - -L, - -L +L, L, L, L, +L, L, +L, L, L, +L, L, L, +L, L, L, +L, L, L, +L, L. =head1 HISTORY