| 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-2004 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 | |