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::Codes::Country, Locale::Country>
  18
  19 This includes support for country codes (such as those listed in ISO-3166)
  20 to specify the country.
  21
  22 Because this module was originally distributed as Locale::Country, it is
  23 also available under that name.
  24
  25 =item B<Locale::Codes::Language, Locale::Language>
  26
  27 This includes support for language codes (such as those listed in ISO-639)
  28 to specify the language.
  29
  30 Because this module was originally distributed as Locale::Language, it is
  31 also available under that name.
  32
  33 =item B<Locale::Codes::Currency, Locale::Currency>
  34
  35 This includes support for currency codes (such as those listed in ISO-4217)
  36 to specify the currency.
  37
  38 Because this module was originally distributed as Locale::Currency, it is
  39 also available under that name.
  40
  41 =item B<Locale::Codes::Script, Locale::Script>
  42
  43 This includes support for script codes (such as those listed in ISO-15924)
  44 to specify the script.
  45
  46 Because this module was originally distributed as Locale::Script, it is
  47 also available under that name.
  48
  49 =item B<Locale::Codes::LangExt>
  50
  51 This includes support for language extension codes (such as those listed
  52 in the IANA language registry) to specify the language extension.
  53
  54 =item B<Locale::Codes::LangVar>
  55
  56 This includes support for language variation codes (such as those listed
  57 in the IANA language registry) to specify the language variation.
  58
  59 =item B<Locale::Codes::LangFam>
  60
  61 This includes support for language family codes (such as those listed
  62 in ISO 639-5) to specify families of languages.
  63
  64 =back
  65
  66 Each module can support an arbitrary number of code sets, and it is
  67 not required that the relationship between these code sets be
  68 one-to-one.  For example, the Locale::Codes::Country module supports
  69 code sets from ISO-3166 and the IANA standard, and they do not
  70 break the world down into exactly the same sets of countries. This
  71 does not cause any problem (though converting codes from ISO-3166 to
  72 IANA or back will not work except for countries that are one-to-one).
  73
  74 All data in all of these modules comes directly from the original
  75 standards (or as close to direct as possible), so it should be
  76 up-to-date at the time of release.
  77
  78 I plan on releasing a new version several times a year to incorporate
  79 any changes made in the standards. However, I don't always know about
  80 changes that occur, so if any of the standards change, and you want a
  81 new release sooner, just email me and I'll get one out.
  82
  83 In addition to the modules above, there are a number of support modules included
  84 in the distribution including:
  85
  86 =over 4
  87
  88 =item B<Locale::Codes>
  89
  90 =item B<Locale::Codes::Constants>
  91
  92 =item B<Locale::Codes::Country_codes>
  93
  94 =item B<Locale::Codes::Language_codes>
  95
  96 =item B<Locale::Codes::Currency_codes>
  97
  98 =item B<Locale::Codes::Script_codes>
  99
 100 =item B<Locale::Codes::LangExt_codes>
 101
 102 =item B<Locale::Codes::LangVar_codes>
 103
 104 =item B<Locale::Codes::LangFam_codes>
 105
 106 =back
 107
 108 These modules are not intended to be used by programmers. They contain functions
 109 or data that are used by the modules listed above.
 110
 111 =head1 NEW CODE SETS
 112
 113 I'm always open to suggestions for new code sets.
 114
 115 In order for me to add a code set, I want the following criteria
 116 to be met:
 117
 118 =over 4
 119
 120 =item B<General-use code set>
 121
 122 If a code set is not general use, I'm not likely to spend the time
 123 to add and support it.
 124
 125 =item B<An official source of data>
 126
 127 I require an official (or at least, a NEARLY official) source where I
 128 can get the data on a regular basis.
 129
 130 Ideally, I'd only get data from an official source, but sometimes that
 131 is not possible. For example the ISO standards are not typically
 132 available for free, so I may have to get some of that data from
 133 alternate sources that I'm confident are getting their data from the
 134 official source.  However, I will always be hesitant to accept a
 135 non-official source.
 136
 137 As an example, I used to get some country data from the CIA World
 138 Factbook. Given the nature of the source, I'm sure they're updating
 139 data from the official sources and I consider it "nearly" official.
 140 However, even in this case, I found that they were adding codes that
 141 were not part of the standard, so I have stopped using them as a
 142 source.
 143
 144 There are many 3rd party sites which maintain lists (many of which are
 145 actually in a more convenient form than the official sites).
 146 Unfortunately, I will reject most of them since I have no feel for how
 147 "official" they are.
 148
 149 =item B<A free source of the data>
 150
 151 Obviously, the data must be free-of-charge. I'm not interested in
 152 paying for the data (and I'm not interested in the overhead of having
 153 someone else pay for the data for me).
 154
 155 =item B<A reliable source of data>
 156
 157 The source of data must come from a source that I can reasonably expect
 158 to exist for the foreseeable future since I will be extremely reluctant
 159 to drop support for a data set once it's included.
 160
 161 I am also reluctant to accept data sent to me by an individual.
 162 Although I appreciate the offer, it is simply not practical to consider
 163 an individual contribution as a reliable source of data. The source
 164 should be an official agency of some sort.
 165
 166 =back
 167
 168 These requirements are open to discussion. If you have a code set
 169 you'd like to see added, but which may not meet all of the above
 170 requirements, feel free to email me and we'll discuss it.  Depending
 171 on circumstances, I may be willing to waive some of these criteria.
 172
 173 =head1 COMMON ALIASES
 174
 175 As of version 2.00, the modules supported common variants of names.
 176
 177 For example, Locale::Country supports variant names for countries, and
 178 a few of the most common ones are included in the data. The country
 179 code for "United States" is "us", so:
 180
 181    country2code('United States');
 182       => "us"
 183
 184 Now the following will also return 'us':
 185
 186    country2code('United States of America');
 187    country2code('USA');
 188
 189 Any number of common aliases may be included in the data, in addition
 190 to the names that come directly from the standards.  If you have a
 191 common alias for a country, language, or any other of the types of
 192 codes, let me know and I'll add it, with some restrictions.
 193
 194 For example, the country name "North Korea" never appeared in any of
 195 the official sources (instead, it was "Korea, North" or "Korea,
 196 Democratic People's Republic of". I would honor a request to add an
 197 alias "North Korea" since that's a very common way to specify the
 198 country (please don't request this... I've already added it).
 199
 200 On the other hand, a request to add Zaire as an alias for "Congo, The
 201 Democratic Republic of" will not be honored. The country's official
 202 name is no longer Zaire, so adding it as an alias violates the standard.
 203 Zaire was kept as an alias in versions prior to 3.00, but it has been
 204 removed. Other aliases (if any) which no longer appear in any standard
 205 (and which are not common variations of the name in the standards)
 206 have also been removed.
 207
 208 =head1 DEPRECATED CODES
 209
 210 Occasionally, a code is deprecated, but it may still be desirable to
 211 have access to it.
 212
 213 Although there is no way to see every code that has ever existed and
 214 been deprecated (since most codesets do not have that information
 215 available), as of version 3.20, every code which has ever been included
 216 in these modules can be referenced.
 217
 218 For more information, refer to the documentation on the code2XXX, XXX2code,
 219 all_XXX_codes, and all_XXX_names function in the B<Locale::Codes::API>
 220 documentation.
 221
 222 =head1 SEE ALSO
 223
 224 =over 4
 225
 226 =item B<Locale::Codes::API>
 227
 228 The list of functions available in each of the modules listed below.
 229 The APIs for each module are exactly identical.
 230
 231 =item B<Locale::Codes::Country>
 232
 233 Codes for identification of countries.
 234
 235 =item B<Locale::Codes::Language>
 236
 237 Codes for identification of languages.
 238
 239 =item B<Locale::Codes::Script>
 240
 241 Codes for identification of scripts.
 242
 243 =item B<Locale::Codes::Currency>
 244
 245 Codes for identification of currencies and funds.
 246
 247 =item B<Locale::Codes::LangExt>
 248
 249 Codes for identification of language extensions.
 250
 251 =item B<Locale::Codes::LangVar>
 252
 253 Codes for identification of language variations.
 254
 255 =item B<Locale::Codes::LangFam>
 256
 257 Codes for identification of language families.
 258
 259 =item B<Locale::Codes::Changes>
 260
 261 A history of changes made to this distribution.
 262
 263 =back
 264
 265 =head1 AUTHOR
 266
 267 Locale::Country and Locale::Language were originally written by Neil
 268 Bowers at the Canon Research Centre Europe (CRE). They maintained the
 269 distribution from 1997 to 2001.
 270
 271 Locale::Currency was originally written by Michael Hennecke and was
 272 modified by Neil Bowers for inclusion in the distribution.
 273
 274 From 2001 to 2004, maintenance was continued by Neil Bowers.  He
 275 modified Locale::Currency for inclusion in the distribution. He also
 276 added Locale::Constants and Locale::Script.
 277
 278 From 2004-2009, the module was unmaintained.
 279
 280 In 2010, maintenance was taken over by Sullivan Beck (sbeck@cpan.org)
 281 with Neil Bower's permission.  All problems or comments should be
 282 sent there.  Alternately, problems can be reported using the
 283 perl problem tracker at:
 284
 285    https://rt.cpan.org/Dist/Display.html?Queue=Locale-Codes
 286
 287 =head1 COPYRIGHT
 288
 289    Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
 290    Copyright (c) 2001      Michael Hennecke (Locale::Currency)
 291    Copyright (c) 2001-2010 Neil Bowers
 292    Copyright (c) 2010-2013 Sullivan Beck
 293
 294 This module is free software; you can redistribute it and/or
 295 modify it under the same terms as Perl itself.
 296
 297 =cut