lib/locale.pm

   1 package locale;
   2
   3 our $VERSION = '1.02';
   4 use Config;
   5
   6 $Carp::Internal{ (__PACKAGE__) } = 1;
   7
   8 =head1 NAME
   9
  10 locale - Perl pragma to use or avoid POSIX locales for built-in operations
  11
  12 =head1 SYNOPSIS
  13
  14     @x = sort @y;       # Unicode sorting order
  15     {
  16         use locale;
  17         @x = sort @y;   # Locale-defined sorting order
  18     }
  19     @x = sort @y;       # Unicode sorting order again
  20
  21 =head1 DESCRIPTION
  22
  23 This pragma tells the compiler to enable (or disable) the use of POSIX
  24 locales for built-in operations (for example, LC_CTYPE for regular
  25 expressions, LC_COLLATE for string comparison, and LC_NUMERIC for number
  26 formatting).  Each "use locale" or "no locale"
  27 affects statements to the end of the enclosing BLOCK.
  28
  29 Starting in Perl 5.16, a hybrid mode for this pragma is available,
  30
  31     use locale ':not_characters';
  32
  33 which enables only the portions of locales that don't affect the character
  34 set (that is, all except LC_COLLATE and LC_CTYPE).  This is useful when mixing
  35 Unicode and locales, including UTF-8 locales.
  36
  37     use locale ':not_characters';
  38     use open ":locale";           # Convert I/O to/from Unicode
  39     use POSIX qw(locale_h);       # Import the LC_ALL constant
  40     setlocale(LC_ALL, "");        # Required for the next statement
  41                                   # to take effect
  42     printf "%.2f\n", 12345.67'    # Locale-defined formatting
  43     @x = sort @y;                 # Unicode-defined sorting order.
  44                                   # (Note that you will get better
  45                                   # results using Unicode::Collate.)
  46
  47 See L<perllocale> for more detailed information on how Perl supports
  48 locales.
  49
  50 =head1 NOTE
  51
  52 If your system does not support locales, then loading this module will
  53 cause the program to die with a message:
  54
  55     "Your vendor does not support locales, you cannot use the locale
  56     module."
  57
  58 =cut
  59
  60 # A separate bit is used for each of the two forms of the pragma, as they are
  61 # mostly independent, and interact with each other and the unicode_strings
  62 # feature.  This allows for fast determination of which one(s) of the three
  63 # are to be used at any given point, and no code has to be written to deal
  64 # with coming in and out of scopes--it falls automatically out from the hint
  65 # handling
  66
  67 $locale::hint_bits = 0x4;
  68 $locale::not_chars_hint_bits = 0x10;
  69
  70 sub import {
  71     shift;  # should be 'locale'; not checked
  72
  73     if(!$Config{d_setlocale}) {
  74         ## No locale support found on this Perl, giving up:
  75         die('Your vendor does not support locales, you cannot use the locale module.');
  76     }
  77
  78     my $found_not_chars = 0;
  79     while (defined (my $arg = shift)) {
  80         if ($arg eq ":not_characters") {
  81             $^H |= $locale::not_chars_hint_bits;
  82
  83             # This form of the pragma overrides the other
  84             $^H &= ~$locale::hint_bits;
  85             $found_not_chars = 1;
  86         }
  87         else {
  88             require Carp;
  89             Carp::croak("Unknown parameter '$arg' to 'use locale'");
  90         }
  91     }
  92
  93     # Use the plain form if not doing the :not_characters one.
  94     $^H |= $locale::hint_bits unless $found_not_chars;
  95 }
  96
  97 sub unimport {
  98     $^H &= ~($locale::hint_bits|$locale::not_chars_hint_bits);
  99 }
 100
 101 1;