cpan/Locale-Codes/lib/Locale/Codes.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Locale::Codes - a distribution of modules to handle locale codes
   6
   7 =head1 DESCRIPTION
   8
   9 B<Locale::Codes> is a distribution containing a set of modules.  The
  10 modules each deal with different types of codes which identify parts
  11 of the locale including languages, countries, currency, etc.
  12
  13 Currently, the following modules are included:
  14
  15 =over 4
  16
  17 =item B<Locale::Country>
  18
  19 This includes support for country codes (such as those listed in ISO-3166)
  20 to specify the country.
  21
  22 =item B<Locale::Language>
  23
  24 This includes support for language codes (such as those listed in ISO-639)
  25 to specify the language.
  26
  27 =item B<Locale::Currency>
  28
  29 This includes support for currency codes (such as those listed in ISO-4217)
  30 to specify the currency.
  31
  32 =item B<Locale::Script>
  33
  34 This includes support for script codes (such as those listed in ISO-15924)
  35 to specify the script.
  36
  37 =back
  38
  39 Each module can support an arbitrary number of code sets, and it it
  40 not required that the relationship between these code sets be
  41 one-to-one.  For example, the Locale::Country module supports code
  42 sets from ISO-3166 and the FIPS 10 standard, and they do not break the
  43 world down into exactly the same sets of countries. This does not
  44 cause any problem (though converting codes from ISO-3166 to FIPS or
  45 back will not work except for countries that are one-to-one).
  46
  47 All data in all of these modules comes directly from the original
  48 standards (or as close to direct as possible), so it should be
  49 up-to-date at the time of release.
  50
  51 I plan on releasing a new version a couple of times a year to
  52 incorporate any changes made in the standards. However, I don't always
  53 know about changes that occur, so if any of the standards change, and
  54 you want a new release sooner, just email me and I'll get one out.
  55
  56 =head1 NEW CODE SETS
  57
  58 I'm always open to suggestions for new code sets.
  59
  60 In order for me to add a code set, I want the following criteria
  61 to be met:
  62
  63 =over 4
  64
  65 =item B<General-use code set>
  66
  67 If a code set is not general use, I'm not likely to spend the time
  68 to add and support it.
  69
  70 =item B<An official source of data>
  71
  72 I require an official (or at least, a NEARLY official) source where I
  73 can get the data on a regular basis.
  74
  75 Ideally, I'd only get data from an official source, but sometimes that
  76 is not possible. For example the ISO standards are not typically
  77 available for free, so I may have to get some of that data from
  78 alternate sources that I'm confident are getting their data from the
  79 official source.
  80
  81 As an example, I get some country data from the CIA World
  82 Factbook. Given the nature of the source, I'm sure they're updating
  83 data from the official sources and I consider it "nearly" official.
  84
  85 There are many 3rd party sites which maintain lists (many of which are
  86 actually in a more convenient form than the official sites).
  87 Unfortunately, I will reject most of them since I have no feel for how
  88 "official" they are.
  89
  90 =item B<A free source of the data>
  91
  92 Obviously, the data must be free-of-charge. I'm not interested in
  93 paying for the data (and I'm not interested in the overhead of having
  94 someone else pay for the data for me).
  95
  96 =item B<A reliable source of data>
  97
  98 The source of data must come from a source that I can reasonably expect
  99 to exist for the foreseeable future since I will be extremely reluctant
 100 to drop support for a data set once it's included.
 101
 102 I am also reluctant to accept data sent to me by an individual.
 103 Although I appreciate the offer, it is simply not practical to consider
 104 an individual contribution as a reliable source of data. The source
 105 should be an official agency of some sort.
 106
 107 =back
 108
 109 These requirements are open to discussion. If you have a code set
 110 you'd like to see added, but which may not meet all of the above
 111 requirements, feel free to email me and we'll discuss it.  Depending
 112 on circumstances, I may be willing to waive some of these criteria.
 113
 114 =head1 COMMON ALIASES
 115
 116 As of version 2.00, the modules supported common variants of names.
 117
 118 For example, Locale::Country supports variant names for countries, and
 119 a few of the most common ones are included in the data. The country
 120 code for "United States" is "us", so:
 121
 122    country2code('United States');
 123       => "us"
 124
 125 Now the following will also return 'us':
 126
 127    country2code('United States of America');
 128    country2code('USA');
 129
 130 Any number of common aliases may be included in the data, in addition
 131 to the names that come directly from the standards.  If you have a
 132 common alias for a country, language, or any other of the types of
 133 codes, let me know and I'll add it, with some restrictions.
 134
 135 For example, the country name "North Korea" never appeared in any of
 136 the official sources (instead, it was "Korea, North" or "Korea,
 137 Democratic People's Republic of". I would honor a request to add an
 138 alias "North Korea" since that's a very common way to specify the
 139 country (please don't request this... I've already added it).
 140
 141 On the other hand, a request to add Zaire as an alias for "Congo, The
 142 Democratic Republic of" may not be honored. The country's official
 143 name is not Zaire, so adding it as an alias violates the standard.
 144 Zaire was kept as an alias in versions prior to 3.00, but it has been
 145 removed. Other aliases (if any) which no longer appear in any standard
 146 have also been removed.
 147
 148 =head1 ROUTINES
 149
 150 As of 3.10, the interface for all of the modules listed above are
 151 identical (as a matter of fact, they are all just wrappers around a
 152 central module which does all the real work).
 153
 154 In order to maintain the documentation for the modules consistently,
 155 the functions are all documented here, rather than in the documentation
 156 for the separate modules.
 157
 158 The name of the function depends on the module. For example, every module
 159 contains a function "code2XXX" where XXX refers to the type of data
 160 (country, language, currency, or script). So, the Locale::Country module
 161 contains the function code2country, the Locale::Language module contains
 162 the function code2language, etc.
 163
 164 In all of the functions below, CODE refers to a code for one element in
 165 the code set. For example, in the two-letter country codes from ISO 3166-1,
 166 the code 'fi' is used to refer to the country Finland. CODE is always
 167 case insensitive (though when a code is returned, it will always be in
 168 the case as used in the standard), so 'fi', 'FI', and 'Fi' would all
 169 be equivalent.
 170
 171 CODESET refers to a constant specified in the documentation for each
 172 module to label the various code sets. For example, in the
 173 Locale::Language module, CODESET could be LOCALE_CODE_ALPHA_2 or
 174 LOCALE_CODE_ALPHA_3 (among others). Most functions have a default one,
 175 so they do not need to be specified. So the following calls are valid:
 176
 177    code2country("fi");
 178    code2country("fi",LOCALE_CODE_ALPHA_2);
 179    code2country("fin",LOCALE_CODE_ALPHA_3);
 180
 181 Since LOCALE_CODE_ALPHA_2 is the default code set, the first two are
 182 identical.
 183
 184 =over 4
 185
 186 =item B<code2country ( CODE [,CODESET] )>
 187
 188 =item B<code2language( CODE [,CODESET] )>
 189
 190 =item B<code2currency( CODE [,CODESET] )>
 191
 192 =item B<code2script  ( CODE [,CODESET] )>
 193
 194 These functions take a code and returns a string which contains
 195 the name of the element identified.  If the code is not a valid
 196 code in the CODESET specified then C<undef> will be returned.
 197
 198 The name of the element is the name as specified in the standard,
 199 and as a result, different variations of an element name may
 200 be returned for different values of CODESET.
 201
 202 For example, the B<alpha-2> country code set defines the two-letter
 203 code "bo" to be "Bolivia, Plurinational State of", whereas the
 204 B<alpha-3> code set defines the code 'bol' to be the country "Bolivia
 205 (Plurinational State of)". So:
 206
 207    code2country('bo',LOCALE_CODE_ALPHA_2);
 208       => 'Bolivia, Plurinational State of'
 209
 210    code2country('bol',LOCALE_CODE_ALPHA_3);
 211       => 'Bolivia (Plurinational State of)'
 212
 213 =item B<country2code ( NAME [,CODESET] )>
 214
 215 =item B<language2code( NAME [,CODESET] )>
 216
 217 =item B<currency2code( NAME [,CODESET] )>
 218
 219 =item B<script2code  ( NAME [,CODESET] )>
 220
 221 These functions takes the name of an element (or any of it's aliases)
 222 and returns the code that corresponds to it, if it exists. If NAME
 223 could not be identified as the name of one of the elements, then
 224 C<undef> will be returned.
 225
 226 The name is not case sensitive. Also, any known variation of a name
 227 may be passed in.
 228
 229 For example, even though the country name returned using
 230 LOCALE_CODE_ALPHA_2 and LOCALE_CODE_ALPHA_3 country codes for Bolivia is different,
 231 either country name may be passed in since for each code set, in addition to
 232 the alias 'Bolivia'. So:
 233
 234    country2code('Bolivia, Plurinational State of',
 235                 LOCALE_CODE_ALPHA_2);
 236       => bo
 237
 238    country2code('Bolivia (Plurinational State of)',
 239                 LOCALE_CODE_ALPHA_2);
 240       => bo
 241
 242    country2code('Bolivia',LOCALE_CODE_ALPHA_2);
 243       => bo
 244
 245 =item B<country_code2code ( CODE ,CODESET ,CODESET2 )>
 246
 247 =item B<language_code2code( CODE ,CODESET ,CODESET2 )>
 248
 249 =item B<currency_code2code( CODE ,CODESET ,CODESET2 )>
 250
 251 =item B<script_code2code  ( CODE ,CODESET ,CODESET2 )>
 252
 253 These functions takes a a code from one code set, and returns the
 254 corresponding code from another code set. CODE must exists in the code
 255 set specified by CODESET and must have a corresponding code in the
 256 code set specified by CODESET2 or C<undef> will be returned.
 257
 258 Both CODESETs must be explicitly entered.
 259
 260    country_code2code('fin', LOCALE_CODE_ALPHA_3,
 261                      LOCALE_CODE_ALPHA_2);
 262       => 'fi'
 263
 264 =item B<all_country_codes ( [CODESET] )>
 265
 266 =item B<all_language_codes( [CODESET] )>
 267
 268 =item B<all_currency_codes( [CODESET] )>
 269
 270 =item B<all_script_codes  ( [CODESET] )>
 271
 272 These returns a list of all code in the code set. The codes will be
 273 sorted.
 274
 275 =item B<all_country_names ( [CODESET] )>
 276
 277 =item B<all_language_names( [CODESET] )>
 278
 279 =item B<all_currency_names( [CODESET] )>
 280
 281 =item B<all_script_names  ( [CODESET] )>
 282
 283 These return a list of all elements names for which there is a
 284 corresponding code in the specified code set.
 285
 286 The names returned are exactly as they are specified in the standard,
 287 and are sorted.
 288
 289 Since not all elements are listed in all code sets, the list of
 290 elements may differ depending on the code set specified.
 291
 292 =back
 293
 294 =head1 SEMI-PRIVATE ROUTINES
 295
 296 Additional semi-private routines which may be used to modify the
 297 internal data are also available.  Given their status, they aren't
 298 exported, and so need to be called by prefixing the function name with
 299 the package name.
 300
 301 =over 4
 302
 303 =item B<Locale::Country::rename_country  ( CODE ,NEW_NAME [,CODESET] )>
 304
 305 =item B<Locale::Language::rename_language( CODE ,NEW_NAME [,CODESET] )>
 306
 307 =item B<Locale::Currency::rename_currency( CODE ,NEW_NAME [,CODESET] )>
 308
 309 =item B<Locale::Script::rename_script    ( CODE ,NEW_NAME [,CODESET] )>
 310
 311 These routines are used to change the official name of an element. At
 312 that point, the name returned by the code2XXX routine would be
 313 NEW_NAME instead of the name specified in the standard.
 314
 315 The original name will remain as an alias.
 316
 317 For example, the official country name for code 'gb' is 'United
 318 Kingdom'.  If you want to change that, you might call:
 319
 320    Locale::Country::rename_country('gb', 'Great Britain');
 321
 322 This means that calling code2country('gb') will now return 'Great
 323 Britain' instead of 'United Kingdom'.
 324
 325 If any error occurs, a warning is issued and 0 is returned. An error
 326 occurs if CODE doesn't exist in the specified code set, or if
 327 NEW_NAME is already in use but for a different element.
 328
 329 If the routine succeeds, 1 is returned.
 330
 331 =item B<Locale::Country::add_country  ( CODE ,NAME [,CODESET] )>
 332
 333 =item B<Locale::Language::add_language( CODE ,NAME [,CODESET] )>
 334
 335 =item B<Locale::Currency::add_currency( CODE ,NAME [,CODESET] )>
 336
 337 =item B<Locale::Script::add_script    ( CODE ,NAME [,CODESET] )>
 338
 339 These routines are used to add a new code and name to the data.
 340
 341 Both CODE and NAME must be unused in the data set or an error
 342 occurs (though NAME may be used in a different data set).
 343
 344 For example, to create the fictitious country named "Duchy of
 345 Grand Fenwick" with codes "gf" and "fen", use the following:
 346
 347    Locale::Country::add_country("fe","Duchy of Grand Fenwick",
 348                                 LOCALE_CODE_ALPHA_2);
 349
 350    Locale::Country::add_country("fen","Duchy of Grand Fenwick",
 351                                 LOCALE_CODE_ALPHA_3);
 352
 353 The return value is 1 on success, 0 on an error.
 354
 355 =item B<Locale::Country::delete_country  ( CODE [,CODESET] )>
 356
 357 =item B<Locale::Language::delete_language( CODE [,CODESET] )>
 358
 359 =item B<Locale::Currency::delete_currency( CODE [,CODESET] )>
 360
 361 =item B<Locale::Script::delete_script    ( CODE [,CODESET] )>
 362
 363 These routines are used to delete a code from the data.
 364
 365 CODE must refer to an existing code in the code set.
 366
 367 The return value is 1 on success, 0 on an error.
 368
 369 =item B<Locale::Country::add_country_alias  ( NAME ,NEW_NAME )>
 370
 371 =item B<Locale::Language::add_language_alias( NAME ,NEW_NAME )>
 372
 373 =item B<Locale::Currency::add_currency_alias( NAME ,NEW_NAME )>
 374
 375 =item B<Locale::Script::add_script_alias    ( NAME ,NEW_NAME )>
 376
 377 These routines are used to add a new alias to the data. They do
 378 not alter the return value of the code2XXX function.
 379
 380 NAME must be an existing element name, and NEW_NAME must
 381 be unused or an error occurs.
 382
 383 The return value is 1 on success, 0 on an error.
 384
 385 =item B<Locale::Country::delete_country_alias  ( NAME )>
 386
 387 =item B<Locale::Language::delete_language_alias( NAME )>
 388
 389 =item B<Locale::Currency::delete_currency_alias( NAME )>
 390
 391 =item B<Locale::Script::delete_script_alias    ( NAME )>
 392
 393 These routines are used to delete an alias from the data. Once
 394 removed, the element may not be referred to by NAME.
 395
 396 NAME must be one of a list of at least two names that may be used to
 397 specify an element. If the element may only be referred to by a single
 398 name, you'll need to use the add_XXX_alias function to add a new alias
 399 first, or the remove_XXX function to remove the element entirely.
 400
 401 If the alias is used as the name in any code set, one of the other
 402 names will be used instead. Predicting exactly which one will
 403 be used requires you to know the order in which the standards
 404 were read, which is not reliable, so you may want to use the
 405 rename_XXX function to force one of the alternate names to be
 406 used.
 407
 408 The return value is 1 on success, 0 on an error.
 409
 410 =item B<Locale::Country::rename_country_code  ( CODE ,NEW_CODE [,CODESET] )>
 411
 412 =item B<Locale::Language::rename_language_code( CODE ,NEW_CODE [,CODESET] )>
 413
 414 =item B<Locale::Currency::rename_currency_code( CODE ,NEW_CODE [,CODESET] )>
 415
 416 =item B<Locale::Script::rename_script_code    ( CODE ,NEW_CODE [,CODESET] )>
 417
 418 These routines are used to change the official code for an element. At
 419 that point, the code returned by the XXX2code routine would be
 420 NEW_CODE instead of the code specified in the standard.
 421
 422 NEW_CODE may either be a code that is not in use, or it may be an
 423 alias for CODE (in which case, CODE becomes and alias and NEW_CODE
 424 becomes the "real" code).
 425
 426 The original code is kept as an alias, so that the code2XXX routines
 427 will work with either the code from the standard or the new code.
 428
 429 However, the all_XXX_codes routine will only return the codes which
 430 are considered "real" (which means that the list of codes will now
 431 contain NEW_CODE, but will not contain CODE).
 432
 433 =item B<Locale::Country::add_country_code_alias  ( CODE ,NEW_CODE [,CODESET] )>
 434
 435 =item B<Locale::Language::add_language_code_alias( CODE ,NEW_CODE [,CODESET] )>
 436
 437 =item B<Locale::Currency::add_currency_code_alias( CODE ,NEW_CODE [,CODESET] )>
 438
 439 =item B<Locale::Script::add_script_code_alias    ( CODE ,NEW_CODE [,CODESET] )>
 440
 441 These routines add an alias for the code. At that point, NEW_CODE and CODE
 442 will both work in the code2XXX routines. However, the XXX2code routines will
 443 still return the original code.
 444
 445 =item B<Locale::Country::delete_country_code_alias  ( CODE [,CODESET] )>
 446
 447 =item B<Locale::Language::delete_language_code_alias( CODE [,CODESET] )>
 448
 449 =item B<Locale::Currency::delete_currency_code_alias( CODE [,CODESET] )>
 450
 451 =item B<Locale::Script::delete_script_code_alias    ( CODE [,CODESET] )>
 452
 453 These routines delete an alias for the code.
 454
 455 These will only work if CODE is actually an alias. If it is the "real"
 456 code, it will not be deleted. You will need to use the rename_XXX_code
 457 function to switch the real code with one of the aliases, and then
 458 delete the alias.
 459
 460 =back
 461
 462 =head1 KNOWN BUGS AND LIMITATIONS
 463
 464 =over 4
 465
 466 =item B<*>
 467
 468 Because each code set uses a slightly different list of elements, and
 469 they are not necessarily one-to-one, there may be some confusion
 470 about the relationship between codes from different code sets.
 471
 472 For example, ISO 3166 assigns one code to the country "United States
 473 Minor Outlying Islands", but the FIPS 10 codes give different codes
 474 to different islands (Baker Island, Howland Island, etc.).
 475
 476 This may cause some confusion... I've done the best that I could do
 477 to minimize it.
 478
 479 =item B<*>
 480
 481 Currently all names must be all ASCII. I plan on relaxing that
 482 limitation in the future.
 483
 484 =back
 485
 486 =head1 SEE ALSO
 487
 488 =over 4
 489
 490 =item B<Locale::Constants>
 491
 492 Constants for Locale codes.
 493
 494 =item B<Locale::Country>
 495
 496 Codes for identification of countries.
 497
 498 =item B<Locale::Language>
 499
 500 Codes for identification of languages.
 501
 502 =item B<Locale::Script>
 503
 504 Codes for identification of scripts.
 505
 506 =item B<Locale::Currency>
 507
 508 Codes for identification of currencies and funds.
 509
 510 =back
 511
 512 =head1 AUTHOR
 513
 514 Locale::Country and Locale::Language were originally written by Neil
 515 Bowers at the Canon Research Centre Europe (CRE). They maintained the
 516 distribution from 1997 to 2001.
 517
 518 Locale::Currency was originally written by Michael Hennecke.
 519
 520 From 2001 to 2004, maintenance was continued by Neil Bowers.  He
 521 modified Locale::Currency for inclusion in the distribution. He also
 522 added Locale::Constants and Locale::Script.
 523
 524 From 2004-2009, the module was unmaintained.
 525
 526 In 2010, maintenance was taken over by Sullivan Beck (sbeck@cpan.org)
 527 with Neil Bower's permission.
 528
 529 =head1 COPYRIGHT
 530
 531    Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
 532    Copyright (c) 2001      Michael Hennecke (Locale::Currency)
 533    Copyright (c) 2001-2010 Neil Bowers
 534    Copyright (c) 2010-2010 Sullivan Beck
 535
 536 This module is free software; you can redistribute it and/or
 537 modify it under the same terms as Perl itself.
 538
 539 =cut
 540