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