lib/Locale/Script.pod

   1
   2 =head1 NAME
   3
   4 Locale::Script - ISO codes for script identification (ISO 15924)
   5
   6 =head1 SYNOPSIS
   7
   8     use Locale::Script;
   9     use Locale::Constants;
  10
  11     $script  = code2script('ph');                       # 'Phoenician'
  12     $code    = script2code('Tibetan');                  # 'bo'
  13     $code3   = script2code('Tibetan',
  14                            LOCALE_CODE_ALPHA_3);        # 'bod'
  15     $codeN   = script2code('Tibetan',
  16                            LOCALE_CODE_ALPHA_NUMERIC);  # 330
  17
  18     @codes   = all_script_codes();
  19     @scripts = all_script_names();
  20
  21
  22 =head1 DESCRIPTION
  23
  24 The C<Locale::Script> module provides access to the ISO
  25 codes for identifying scripts, as defined in ISO 15924.
  26 For example, Egyptian hieroglyphs are denoted by the two-letter
  27 code 'eg', the three-letter code 'egy', and the numeric code 050.
  28
  29 You can either access the codes via the conversion routines
  30 (described below), or with the two functions which return lists
  31 of all script codes or all script names.
  32
  33 There are three different code sets you can use for identifying
  34 scripts:
  35
  36 =over 4
  37
  38 =item B<alpha-2>
  39
  40 Two letter codes, such as 'bo' for Tibetan.
  41 This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.
  42
  43 =item B<alpha-3>
  44
  45 Three letter codes, such as 'ell' for Greek.
  46 This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.
  47
  48 =item B<numeric>
  49
  50 Numeric codes, such as 410 for Hiragana.
  51 This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>.
  52
  53 =back
  54
  55 All of the routines take an optional additional argument
  56 which specifies the code set to use.
  57 If not specified, it defaults to the two-letter codes.
  58 This is partly for backwards compatibility (previous versions
  59 of Locale modules only supported the alpha-2 codes), and
  60 partly because they are the most widely used codes.
  61
  62 The alpha-2 and alpha-3 codes are not case-dependent,
  63 so you can use 'BO', 'Bo', 'bO' or 'bo' for Tibetan.
  64 When a code is returned by one of the functions in
  65 this module, it will always be lower-case.
  66
  67 =head2 SPECIAL CODES
  68
  69 The standard defines various special codes.
  70
  71 =over 4
  72
  73 =item *
  74
  75 The standard reserves codes in the ranges B<qa> - B<qt>,
  76 B<qaa> - B<qat>, and B<900> - B<919>, for private use.
  77
  78 =item *
  79
  80 B<zx>, B<zxx>, and B<997>, are the codes for unwritten languages.
  81
  82 =item *
  83
  84 B<zy>, B<zyy>, and B<998>, are the codes for an undetermined script.
  85
  86 =item *
  87
  88 B<zz>, B<zzz>, and B<999>, are the codes for an uncoded script.
  89
  90 =back
  91
  92 The private codes are not recognised by Locale::Script,
  93 but the others are.
  94
  95
  96 =head1 CONVERSION ROUTINES
  97
  98 There are three conversion routines: C<code2script()>, C<script2code()>,
  99 and C<script_code2code()>.
 100
 101 =over 4
 102
 103 =item code2script( CODE, [ CODESET ] )
 104
 105 This function takes a script code and returns a string
 106 which contains the name of the script identified.
 107 If the code is not a valid script code, as defined by ISO 15924,
 108 then C<undef> will be returned:
 109
 110     $script = code2script('cy');   # Cyrillic
 111
 112 =item script2code( STRING, [ CODESET ] )
 113
 114 This function takes a script name and returns the corresponding
 115 script code, if such exists.
 116 If the argument could not be identified as a script name,
 117 then C<undef> will be returned:
 118
 119     $code = script2code('Gothic', LOCALE_CODE_ALPHA_3);
 120     # $code will now be 'gth'
 121
 122 The case of the script name is not important.
 123 See the section L<KNOWN BUGS AND LIMITATIONS> below.
 124
 125 =item script_code2code( CODE, CODESET, CODESET )
 126
 127 This function takes a script code from one code set,
 128 and returns the corresponding code from another code set.
 129
 130     $alpha2 = script_code2code('jwi',
 131                  LOCALE_CODE_ALPHA_3 => LOCALE_CODE_ALPHA_2);
 132     # $alpha2 will now be 'jw' (Javanese)
 133
 134 If the code passed is not a valid script code in
 135 the first code set, or if there isn't a code for the
 136 corresponding script in the second code set,
 137 then C<undef> will be returned.
 138
 139 =back
 140
 141
 142 =head1 QUERY ROUTINES
 143
 144 There are two function which can be used to obtain a list of all codes,
 145 or all script names:
 146
 147 =over 4
 148
 149 =item C<all_script_codes ( [ CODESET ] )>
 150
 151 Returns a list of all two-letter script codes.
 152 The codes are guaranteed to be all lower-case,
 153 and not in any particular order.
 154
 155 =item C<all_script_names ( [ CODESET ] )>
 156
 157 Returns a list of all script names for which there is a corresponding
 158 script code in the specified code set.
 159 The names are capitalised, and not returned in any particular order.
 160
 161 =back
 162
 163
 164 =head1 EXAMPLES
 165
 166 The following example illustrates use of the C<code2script()> function.
 167 The user is prompted for a script code, and then told the corresponding
 168 script name:
 169
 170     $| = 1;   # turn off buffering
 171
 172     print "Enter script code: ";
 173     chop($code = <STDIN>);
 174     $script = code2script($code, LOCALE_CODE_ALPHA_2);
 175     if (defined $script)
 176     {
 177         print "$code = $script\n";
 178     }
 179     else
 180     {
 181         print "'$code' is not a valid script code!\n";
 182     }
 183
 184
 185 =head1 KNOWN BUGS AND LIMITATIONS
 186
 187 =over 4
 188
 189 =item *
 190
 191 When using C<script2code()>, the script name must currently appear
 192 exactly as it does in the source of the module. For example,
 193
 194     script2code('Egyptian hieroglyphs')
 195
 196 will return B<eg>, as expected. But the following will all return C<undef>:
 197
 198     script2code('hieroglyphs')
 199     script2code('Egyptian Hieroglypics')
 200
 201 If there's need for it, a future version could have variants
 202 for script names.
 203
 204 =item *
 205
 206 In the current implementation, all data is read in when the
 207 module is loaded, and then held in memory.
 208 A lazy implementation would be more memory friendly.
 209
 210 =back
 211
 212 =head1 SEE ALSO
 213
 214 =over 4
 215
 216 =item Locale::Language
 217
 218 ISO two letter codes for identification of language (ISO 639).
 219
 220 =item Locale::Currency
 221
 222 ISO three letter codes for identification of currencies
 223 and funds (ISO 4217).
 224
 225 =item Locale::Country
 226
 227 ISO three letter codes for identification of countries (ISO 3166)
 228
 229 =item ISO 15924
 230
 231 The ISO standard which defines these codes.
 232
 233 =item http://www.evertype.com/standards/iso15924/
 234
 235 Home page for ISO 15924.
 236
 237
 238 =back
 239
 240
 241 =head1 AUTHOR
 242
 243 Neil Bowers E<lt>neil@bowers.comE<gt>
 244
 245 =head1 COPYRIGHT
 246
 247 Copyright (c) 2002 Neil Bowers.
 248
 249 This module is free software; you can redistribute it and/or
 250 modify it under the same terms as Perl itself.
 251
 252 =cut
 253