1package I18N::Langinfo; 2 3use 5.006; 4use strict; 5use warnings; 6use Carp; 7 8use Exporter 'import'; 9require XSLoader; 10 11our @EXPORT = qw(langinfo); 12 13our @EXPORT_OK = qw( 14 ABDAY_1 15 ABDAY_2 16 ABDAY_3 17 ABDAY_4 18 ABDAY_5 19 ABDAY_6 20 ABDAY_7 21 ABMON_1 22 ABMON_2 23 ABMON_3 24 ABMON_4 25 ABMON_5 26 ABMON_6 27 ABMON_7 28 ABMON_8 29 ABMON_9 30 ABMON_10 31 ABMON_11 32 ABMON_12 33 ALT_DIGITS 34 AM_STR 35 CODESET 36 CRNCYSTR 37 DAY_1 38 DAY_2 39 DAY_3 40 DAY_4 41 DAY_5 42 DAY_6 43 DAY_7 44 D_FMT 45 D_T_FMT 46 ERA 47 ERA_D_FMT 48 ERA_D_T_FMT 49 ERA_T_FMT 50 MON_1 51 MON_2 52 MON_3 53 MON_4 54 MON_5 55 MON_6 56 MON_7 57 MON_8 58 MON_9 59 MON_10 60 MON_11 61 MON_12 62 NOEXPR 63 NOSTR 64 PM_STR 65 RADIXCHAR 66 THOUSEP 67 T_FMT 68 T_FMT_AMPM 69 YESEXPR 70 YESSTR 71 _NL_ADDRESS_POSTAL_FMT 72 _NL_ADDRESS_COUNTRY_NAME 73 _NL_ADDRESS_COUNTRY_POST 74 _NL_ADDRESS_COUNTRY_AB2 75 _NL_ADDRESS_COUNTRY_AB3 76 _NL_ADDRESS_COUNTRY_CAR 77 _NL_ADDRESS_COUNTRY_NUM 78 _NL_ADDRESS_COUNTRY_ISBN 79 _NL_ADDRESS_LANG_NAME 80 _NL_ADDRESS_LANG_AB 81 _NL_ADDRESS_LANG_TERM 82 _NL_ADDRESS_LANG_LIB 83 _NL_IDENTIFICATION_TITLE 84 _NL_IDENTIFICATION_SOURCE 85 _NL_IDENTIFICATION_ADDRESS 86 _NL_IDENTIFICATION_CONTACT 87 _NL_IDENTIFICATION_EMAIL 88 _NL_IDENTIFICATION_TEL 89 _NL_IDENTIFICATION_FAX 90 _NL_IDENTIFICATION_LANGUAGE 91 _NL_IDENTIFICATION_TERRITORY 92 _NL_IDENTIFICATION_AUDIENCE 93 _NL_IDENTIFICATION_APPLICATION 94 _NL_IDENTIFICATION_ABBREVIATION 95 _NL_IDENTIFICATION_REVISION 96 _NL_IDENTIFICATION_DATE 97 _NL_IDENTIFICATION_CATEGORY 98 _NL_MEASUREMENT_MEASUREMENT 99 _NL_NAME_NAME_FMT 100 _NL_NAME_NAME_GEN 101 _NL_NAME_NAME_MR 102 _NL_NAME_NAME_MRS 103 _NL_NAME_NAME_MISS 104 _NL_NAME_NAME_MS 105 _NL_PAPER_HEIGHT 106 _NL_PAPER_WIDTH 107 _NL_TELEPHONE_TEL_INT_FMT 108 _NL_TELEPHONE_TEL_DOM_FMT 109 _NL_TELEPHONE_INT_SELECT 110 _NL_TELEPHONE_INT_PREFIX 111 ); 112 113our $VERSION = '0.24'; 114 115XSLoader::load(); 116 1171; 118__END__ 119 120=encoding utf8 121 122=head1 NAME 123 124I18N::Langinfo - query locale information 125 126=head1 SYNOPSIS 127 128 use I18N::Langinfo; 129 130=head1 DESCRIPTION 131 132The langinfo() function queries various locale information that can be 133used to localize output and user interfaces. It uses the current underlying 134locale, regardless of whether or not it was called from within the scope of 135S<C<use locale>>. The langinfo() function requires 136one numeric argument that identifies the locale constant to query: 137if no argument is supplied, C<$_> is used. The numeric constants 138appropriate to be used as arguments are exportable from I18N::Langinfo. 139 140The following example will import the langinfo() function itself and 141three constants to be used as arguments to langinfo(): a constant for 142the abbreviated first day of the week (the numbering starts from 143Sunday = 1) and two more constants for the affirmative and negative 144answers for a yes/no question in the current locale. 145 146 use I18N::Langinfo qw(langinfo ABDAY_1 YESSTR NOSTR); 147 148 my ($abday_1, $yesstr, $nostr) = 149 map { langinfo($_) } (ABDAY_1, YESSTR, NOSTR); 150 151 print "$abday_1? [$yesstr/$nostr] "; 152 153In other words, in the "C" (or English) locale the above will probably 154print something like: 155 156 Sun? [yes/no] 157 158but under a French locale 159 160 dim? [oui/non] 161 162The usually available constants are as follows. 163 164=over 4 165 166=item * 167 168For abbreviated and full length days of the week and months of the year: 169 170 ABDAY_1 ABDAY_2 ABDAY_3 ABDAY_4 ABDAY_5 ABDAY_6 ABDAY_7 171 ABMON_1 ABMON_2 ABMON_3 ABMON_4 ABMON_5 ABMON_6 172 ABMON_7 ABMON_8 ABMON_9 ABMON_10 ABMON_11 ABMON_12 173 DAY_1 DAY_2 DAY_3 DAY_4 DAY_5 DAY_6 DAY_7 174 MON_1 MON_2 MON_3 MON_4 MON_5 MON_6 175 MON_7 MON_8 MON_9 MON_10 MON_11 MON_12 176 177=item * 178 179For the date-time, date, and time formats used by the strftime() function 180(see L<POSIX>): 181 182 D_T_FMT D_FMT T_FMT 183 184=item * 185 186For the locales for which it makes sense to have ante meridiem and post 187meridiem time formats: 188 189 AM_STR PM_STR T_FMT_AMPM 190 191=item * 192 193For the character code set being used (such as "ISO8859-1", "cp850", 194"koi8-r", "sjis", "utf8", etc.): 195 196 CODESET 197 198=item * 199 200For the symbol or string of characters that indicates a number is a monetary 201value: 202 203 CRNCYSTR 204 205An example is the dollar sign C<$>. Some locales not associated with 206particular locations may have an empty currency string. (The C locale is 207one.) Otherwise, the return of this is always prefixed by one of these three 208characters: 209 210=over 211 212=item C<-> 213 214indicates that in this locale, the string precedes the numeric value, as in a 215U.S. locale: C<$9.95>. 216 217=item C<+> 218 219indicates that in this locale, the string follows the numeric value, like 220C<9.95USD>. 221 222=item C<.> 223 224indicates that in this locale, the string replaces the radix character, like 225C<9$95>. 226 227=back 228 229=item * 230 231For the radix character used between the integer and the fractional part of 232decimal numbers, and the group separator string for large-ish floating point 233numbers (yes, these are redundant with 234L<POSIX::localeconv()|POSIX/localeconv>): 235 236 RADIXCHAR THOUSEP 237 238=item * 239 240For any alternate digits used in this locale besides the standard C<0..9>: 241 242 ALT_DIGITS 243 244This returns a sequence of alternate numeric reprsesentations for the numbers 245C<0> ... up to C<99>. The representations are returned in a single string, 246with a semi-colon C<;> used to separated the individual ones. 247 248Most locales don't have alternate digits, so the string will be empty. 249 250To access this data conveniently, you could do something like 251 252 use I18N::Langinfo qw(langinfo ALT_DIGITS); 253 my @alt_digits = split ';', langinfo(ALT_DIGITS); 254 255The array C<@alt_digits> will contain 0 elements if the current locale doesn't 256have alternate digits specified for it. Otherwise, it will have as many 257elements as the locale defines, with C<[0]> containing the alternate digit for 258zero; C<[1]> for one; and so forth, up to potentially C<[99]> for the 259alternate representation of ninety-nine. 260 261Be aware that the alternate representation in some locales for the numbers 2620..9 will have a leading alternate-zero, so would look like the equivalent of 26300..09. 264 265Running this program 266 267 use I18N::Langinfo qw(langinfo ALT_DIGITS); 268 my @alt_digits = split ';', langinfo(ALT_DIGITS); 269 splice @alt_digits, 15; 270 print join " ", @alt_digits, "\n"; 271 272on a Japanese locale yields 273 274S<C<〇 一 二 三 四 五 六 七 八 九 十 十一 十二 十三 十四>> 275 276on some platforms. 277 278=item * 279 280For the affirmative and negative responses and expressions: 281 282 YESSTR YESEXPR NOSTR NOEXPR 283 284=item * 285 286For the eras based on typically some ruler, such as the Japanese Emperor 287(naturally only defined in the appropriate locales): 288 289 ERA ERA_D_FMT ERA_D_T_FMT ERA_T_FMT 290 291=back 292 293In addition, Linux boxes have extra items, as follows. (When called from 294other platform types, these return a stub value, of not much use.) 295 296=over 297 298=item C<_NL_ADDRESS_POSTAL_FMT> 299 300=item C<_NL_ADDRESS_COUNTRY_NAME> 301 302=item C<_NL_ADDRESS_COUNTRY_POST> 303 304=item C<_NL_ADDRESS_COUNTRY_AB2> 305 306=item C<_NL_ADDRESS_COUNTRY_AB3> 307 308=item C<_NL_ADDRESS_COUNTRY_CAR> 309 310=item C<_NL_ADDRESS_COUNTRY_NUM> 311 312=item C<_NL_ADDRESS_COUNTRY_ISBN> 313 314=item C<_NL_ADDRESS_LANG_NAME> 315 316=item C<_NL_ADDRESS_LANG_AB> 317 318=item C<_NL_ADDRESS_LANG_TERM> 319 320=item C<_NL_ADDRESS_LANG_LIB> 321 322On Linux boxes, these return information about the country for the current 323locale. Further information is found in F<langinfo.h> 324 325=item C<_NL_IDENTIFICATION_TITLE> 326 327=item C<_NL_IDENTIFICATION_SOURCE> 328 329=item C<_NL_IDENTIFICATION_ADDRESS> 330 331=item C<_NL_IDENTIFICATION_CONTACT> 332 333=item C<_NL_IDENTIFICATION_EMAIL> 334 335=item C<_NL_IDENTIFICATION_TEL> 336 337=item C<_NL_IDENTIFICATION_FAX> 338 339=item C<_NL_IDENTIFICATION_LANGUAGE> 340 341=item C<_NL_IDENTIFICATION_TERRITORY> 342 343=item C<_NL_IDENTIFICATION_AUDIENCE> 344 345=item C<_NL_IDENTIFICATION_APPLICATION> 346 347=item C<_NL_IDENTIFICATION_ABBREVIATION> 348 349=item C<_NL_IDENTIFICATION_REVISION> 350 351=item C<_NL_IDENTIFICATION_DATE> 352 353=item C<_NL_IDENTIFICATION_CATEGORY> 354 355On Linux boxes, these return meta information about the current locale, 356such as how to get in touch with its maintainers. 357Further information is found in F<langinfo.h> 358 359=item C<_NL_MEASUREMENT_MEASUREMENT> 360 361On Linux boxes, it returns 1 if the metric system of measurement prevails in 362the locale; or 2 if US customary units prevail. 363 364=item C<_NL_NAME_NAME_FMT> 365 366=item C<_NL_NAME_NAME_GEN> 367 368=item C<_NL_NAME_NAME_MR> 369 370=item C<_NL_NAME_NAME_MRS> 371 372=item C<_NL_NAME_NAME_MISS> 373 374=item C<_NL_NAME_NAME_MS> 375 376On Linux boxes, these return information about how names are formatted and 377the personal salutations used in the current locale. Further information 378is found in L<locale(7)> and F<langinfo.h> 379 380=item C<_NL_PAPER_HEIGHT> 381 382=item C<_NL_PAPER_WIDTH> 383 384On Linux boxes, these return the standard size of sheets of paper (in 385millimeters) in the current locale. 386 387=item C<_NL_TELEPHONE_TEL_INT_FMT> 388 389=item C<_NL_TELEPHONE_TEL_DOM_FMT> 390 391=item C<_NL_TELEPHONE_INT_SELECT> 392 393=item C<_NL_TELEPHONE_INT_PREFIX> 394 395On Linux boxes, these return information about how telephone numbers are 396formatted (both domestically and international calling) in the current locale. 397Further information is found in F<langinfo.h> 398 399=back 400 401=head2 For systems without C<nl_langinfo> 402 403This module originally was just a wrapper for the libc C<nl_langinfo> 404function, and did not work on systems lacking it, such as Windows. 405 406Starting in Perl 5.28, this module works on all platforms. When 407C<nl_langinfo> is not available, it uses various methods to construct 408what that function, if present, would return. But there are potential 409glitches. These are the items that could be different: 410 411=over 412 413=item C<ERA> 414 415Unimplemented, so returns C<"">. 416 417=item C<CODESET> 418 419This should work properly for Windows platforms. On almost all other modern 420platforms, it will reliably return "UTF-8" if that is the code set. 421Otherwise, it depends on the locale's name. If that is of the form 422C<foo.bar>, it will assume C<bar> is the code set; and it also knows about the 423two locales "C" and "POSIX". If none of those apply it returns C<"">. 424 425=item C<YESEXPR> 426 427=item C<YESSTR> 428 429=item C<NOEXPR> 430 431=item C<NOSTR> 432 433Only the values for English are returned. C<YESSTR> and C<NOSTR> have been 434removed from POSIX 2008, and are retained here for backwards compatibility. 435Your platform's C<nl_langinfo> may not support them. 436 437=item C<ALT_DIGITS> 438 439On systems with a C<L<strftime(3)>> that recognizes the POSIX-defined C<%O> 440format modifier (not Windows), perl tries hard to return these. The result 441likely will go as high as what C<nl_langinfo()> would return, but not 442necessarily; and the numbers from C<0..9> will always be stripped of leading 443zeros. 444 445Without C<%O>, an empty string is always returned. 446 447=item C<D_FMT> 448 449Always evaluates to C<%x>, the locale's appropriate date representation. 450 451=item C<T_FMT> 452 453Always evaluates to C<%X>, the locale's appropriate time representation. 454 455=item C<D_T_FMT> 456 457Always evaluates to C<%c>, the locale's appropriate date and time 458representation. 459 460=item C<CRNCYSTR> 461 462The return may be incorrect for those rare locales where the currency symbol 463replaces the radix character. If you have examples of it needing to work 464differently, please file a report at L<https://github.com/Perl/perl5/issues>. 465 466=item C<ERA_D_FMT> 467 468=item C<ERA_T_FMT> 469 470=item C<ERA_D_T_FMT> 471 472=item C<T_FMT_AMPM> 473 474These are derived by using C<strftime()>, and not all versions of that function 475know about them. C<""> is returned for these on such systems. 476 477=item All C<_NL_I<foo>> items 478 479These return the same values as they do on boxes that don't have the 480appropriate underlying locale categories. 481 482=back 483 484See your L<nl_langinfo(3)> for more information about the available 485constants. (Often this means having to look directly at the 486F<langinfo.h> C header file.) 487 488=head2 EXPORT 489 490By default only the C<langinfo()> function is exported. 491 492=head1 BUGS 493 494Before Perl 5.28, the returned values are unreliable for the C<RADIXCHAR> and 495C<THOUSEP> locale constants. 496 497Starting in 5.28, changing locales on threaded builds is supported on systems 498that offer thread-safe locale functions. These include POSIX 2008 systems and 499Windows starting with Visual Studio 2005, and this module will work properly 500in such situations. However, on threaded builds on Windows prior to Visual 501Studio 2015, retrieving the items C<CRNCYSTR> and C<THOUSEP> can result in a 502race with a thread that has converted to use the global locale. It is quite 503uncommon for a thread to have done this. It would be possible to construct a 504workaround for this; patches welcome: see L<perlapi/switch_to_global_locale>. 505 506=head1 SEE ALSO 507 508L<perllocale>, L<POSIX/localeconv>, L<POSIX/setlocale>, L<nl_langinfo(3)>. 509 510=head1 AUTHOR 511 512Jarkko Hietaniemi, E<lt>jhi@hut.fiE<gt>. Now maintained by Perl 5 porters. 513 514=head1 COPYRIGHT AND LICENSE 515 516Copyright 2001 by Jarkko Hietaniemi 517 518This library is free software; you can redistribute it and/or modify 519it under the same terms as Perl itself. 520 521=cut 522