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

   1 =pod
   2
   3 =head1 NAME
   4
   5 Locale::Codes::API - a description of the callable function in each module
   6
   7 =head1 DESCRIPTION
   8
   9 Although there are several modules in the Locale-Codes distribution, all of them
  10 (as of version 3.10) use exactly the same API.  As a matter of fact, each of the
  11 main callable modules are just wrappers around a central module which does all
  12 the real work.
  13
  14 =head1 ROUTINES
  15
  16 In order to maintain the documentation for the modules consistently,
  17 the functions are all documented here, rather than in the documentation
  18 for the separate modules.
  19
  20 The name of the function depends on the module. For example, every module
  21 contains a function "code2XXX" where XXX refers to the type of data.
  22 The values of XXX are described in the following table:
  23
  24    XXX       MODULE
  25
  26    country   Locale::Codes::Country
  27    language  Locale::Codes::Language
  28    currency  Locale::Codes::Currency
  29    script    Locale::Codes::Script
  30    langext   Locale::Codes::LangExt
  31    langvar   Locale::Codes::LangVar
  32    langfam   Locale::Codes::LangFAM
  33
  34 So, the Locale::Country module contains the function code2country, the
  35 Locale::Language module contains the function code2language, etc.
  36
  37 In all of the functions below, CODE refers to a code for one element in
  38 the code set. For example, in the two-letter country codes from ISO 3166-1,
  39 the code 'fi' is used to refer to the country Finland. CODE is always
  40 case insensitive (though when a code is returned, it will always be in
  41 the case as used in the standard), so 'fi', 'FI', and 'Fi' would all
  42 be equivalent.
  43
  44 CODESET refers to a constant specified in the documentation for each
  45 module to label the various code sets. For example, in the
  46 Locale::Language module, CODESET could be LOCALE_CODE_ALPHA_2 or
  47 LOCALE_CODE_ALPHA_3 (among others). Most functions have a default one,
  48 so they do not need to be specified. So the following calls are valid:
  49
  50    code2country("fi");
  51    code2country("fi",LOCALE_CODE_ALPHA_2);
  52    code2country("fin",LOCALE_CODE_ALPHA_3);
  53
  54 Since LOCALE_CODE_ALPHA_2 is the default code set, the first two are
  55 identical.
  56
  57 =over 4
  58
  59 =item B<code2XXX ( CODE [,CODESET] [,'retired'] )>
  60
  61 These functions take a code and returns a string which contains
  62 the name of the element identified.  If the code is not a valid
  63 code in the CODESET specified then C<undef> will be returned.
  64
  65 The name of the element is the name as specified in the standard,
  66 and as a result, different variations of an element name may
  67 be returned for different values of CODESET.
  68
  69 For example, the B<alpha-2> country code set defines the two-letter
  70 code "bo" to be "Bolivia, Plurinational State of", whereas the
  71 B<alpha-3> code set defines the code 'bol' to be the country "Bolivia
  72 (Plurinational State of)". So:
  73
  74    code2country('bo',LOCALE_CODE_ALPHA_2);
  75       => 'Bolivia, Plurinational State of'
  76
  77    code2country('bol',LOCALE_CODE_ALPHA_3);
  78       => 'Bolivia (Plurinational State of)'
  79
  80 By default, only active codes will be used, but if the string
  81 'retired' is passed in as an argument, both active and retired
  82 codes will be examined.
  83
  84 =item B<XXX2code ( NAME [,CODESET] [,'retired'] )>
  85
  86 These functions takes the name of an element (or any of it's aliases)
  87 and returns the code that corresponds to it, if it exists. If NAME
  88 could not be identified as the name of one of the elements, then
  89 C<undef> will be returned.
  90
  91 The name is not case sensitive. Also, any known variation of a name
  92 may be passed in.
  93
  94 For example, even though the country name returned using
  95 LOCALE_CODE_ALPHA_2 and LOCALE_CODE_ALPHA_3 country codes for Bolivia is different,
  96 either country name may be passed in since for each code set, in addition to
  97 the alias 'Bolivia'. So:
  98
  99    country2code('Bolivia, Plurinational State of',
 100                 LOCALE_CODE_ALPHA_2);
 101       => bo
 102
 103    country2code('Bolivia (Plurinational State of)',
 104                 LOCALE_CODE_ALPHA_2);
 105       => bo
 106
 107    country2code('Bolivia',LOCALE_CODE_ALPHA_2);
 108       => bo
 109
 110 By default, only active names will be used, but if the string
 111 'retired' is passed in as an argument, both active and retired
 112 names will be examined.
 113
 114 =item B<XXX_code2code ( CODE ,CODESET ,CODESET2 )>
 115
 116 These functions takes a code from one code set, and returns the
 117 corresponding code from another code set. CODE must exists in the code
 118 set specified by CODESET and must have a corresponding code in the
 119 code set specified by CODESET2 or C<undef> will be returned.
 120
 121 Both CODESETs must be explicitly entered.
 122
 123    country_code2code('fin', LOCALE_CODE_ALPHA_3,
 124                      LOCALE_CODE_ALPHA_2);
 125       => 'fi'
 126
 127 Note that this function does NOT support retired codes.
 128
 129 =item B<all_XXX_codes ( [CODESET] [,'retired'] )>
 130
 131 These returns a list of all code in the code set. The codes will be
 132 sorted.
 133
 134 By default, only active codes will be returned, but if the string
 135 'retired' is passed in as an argument, both active and retired
 136 codes will be returned.
 137
 138 =item B<all_XXX_names ( [CODESET] [,'retired'] )>
 139
 140 These return a list of all elements names for which there is a
 141 corresponding code in the specified code set.
 142
 143 The names returned are exactly as they are specified in the standard,
 144 and are sorted.
 145
 146 Since not all elements are listed in all code sets, the list of
 147 elements may differ depending on the code set specified.
 148
 149 By default, only active names will be returned, but if the string
 150 'retired' is passed in as an argument, both active and retired
 151 names will be returned.
 152
 153 =back
 154
 155 =head1 SEMI-PRIVATE ROUTINES
 156
 157 Additional semi-private routines which may be used to modify the
 158 internal data are also available.  Given their status, they aren't
 159 exported, and so need to be called by prefixing the function name with
 160 the package name.
 161
 162 These routines do not currently work with retired codes.
 163
 164 =over 4
 165
 166 =item B<MODULE::rename_XXX  ( CODE ,NEW_NAME [,CODESET] )>
 167
 168 These routines are used to change the official name of an element. At
 169 that point, the name returned by the code2XXX routine would be
 170 NEW_NAME instead of the name specified in the standard.
 171
 172 The original name will remain as an alias.
 173
 174 For example, the official country name for code 'gb' is 'United
 175 Kingdom'.  If you want to change that, you might call:
 176
 177    Locale::Codes::Country::rename_country('gb', 'Great Britain');
 178
 179 This means that calling code2country('gb') will now return 'Great
 180 Britain' instead of 'United Kingdom'.
 181
 182 If any error occurs, a warning is issued and 0 is returned. An error
 183 occurs if CODE doesn't exist in the specified code set, or if
 184 NEW_NAME is already in use but for a different element.
 185
 186 If the routine succeeds, 1 is returned.
 187
 188 =item B<MODULE::add_XXX  ( CODE ,NAME [,CODESET] )>
 189
 190 These routines are used to add a new code and name to the data.
 191
 192 Both CODE and NAME must be unused in the data set or an error
 193 occurs (though NAME may be used in a different data set).
 194
 195 For example, to create the fictitious country named "Duchy of
 196 Grand Fenwick" with codes "gf" and "fen", use the following:
 197
 198    Locale::Codes::Country::add_country("fe","Duchy of Grand Fenwick",
 199                                 LOCALE_CODE_ALPHA_2);
 200
 201    Locale::Codes::Country::add_country("fen","Duchy of Grand Fenwick",
 202                                 LOCALE_CODE_ALPHA_3);
 203
 204 The return value is 1 on success, 0 on an error.
 205
 206 =item B<MODULE::delete_XXX  ( CODE [,CODESET] )>
 207
 208 These routines are used to delete a code from the data.
 209
 210 CODE must refer to an existing code in the code set.
 211
 212 The return value is 1 on success, 0 on an error.
 213
 214 =item B<MODULE::add_XXX_alias  ( NAME ,NEW_NAME )>
 215
 216 These routines are used to add a new alias to the data. They do
 217 not alter the return value of the code2XXX function.
 218
 219 NAME must be an existing element name, and NEW_NAME must
 220 be unused or an error occurs.
 221
 222 The return value is 1 on success, 0 on an error.
 223
 224 =item B<MODULE::delete_XXX_alias  ( NAME )>
 225
 226 These routines are used to delete an alias from the data. Once
 227 removed, the element may not be referred to by NAME.
 228
 229 NAME must be one of a list of at least two names that may be used to
 230 specify an element. If the element may only be referred to by a single
 231 name, you'll need to use the add_XXX_alias function to add a new alias
 232 first, or the remove_XXX function to remove the element entirely.
 233
 234 If the alias is used as the name in any code set, one of the other
 235 names will be used instead. Predicting exactly which one will
 236 be used requires you to know the order in which the standards
 237 were read, which is not reliable, so you may want to use the
 238 rename_XXX function to force one of the alternate names to be
 239 used.
 240
 241 The return value is 1 on success, 0 on an error.
 242
 243 =item B<MODULE::rename_XXX_code  ( CODE ,NEW_CODE [,CODESET] )>
 244
 245 These routines are used to change the official code for an element. At
 246 that point, the code returned by the XXX2code routine would be
 247 NEW_CODE instead of the code specified in the standard.
 248
 249 NEW_CODE may either be a code that is not in use, or it may be an
 250 alias for CODE (in which case, CODE becomes and alias and NEW_CODE
 251 becomes the "real" code).
 252
 253 The original code is kept as an alias, so that the code2XXX routines
 254 will work with either the code from the standard or the new code.
 255
 256 However, the all_XXX_codes routine will only return the codes which
 257 are considered "real" (which means that the list of codes will now
 258 contain NEW_CODE, but will not contain CODE).
 259
 260 =item B<MODULE::add_XXX_code_alias  ( CODE ,NEW_CODE [,CODESET] )>
 261
 262 These routines add an alias for the code. At that point, NEW_CODE and CODE
 263 will both work in the code2XXX routines. However, the XXX2code routines will
 264 still return the original code.
 265
 266 =item B<MODULE::delete_XXX_code_alias  ( CODE [,CODESET] )>
 267
 268 These routines delete an alias for the code.
 269
 270 These will only work if CODE is actually an alias. If it is the "real"
 271 code, it will not be deleted. You will need to use the rename_XXX_code
 272 function to switch the real code with one of the aliases, and then
 273 delete the alias.
 274
 275 =back
 276
 277 =head1 KNOWN BUGS AND LIMITATIONS
 278
 279 =over 4
 280
 281 =item B<Relationship between code sets>
 282
 283 Because each code set uses a slightly different list of elements, and
 284 they are not necessarily one-to-one, there may be some confusion
 285 about the relationship between codes from different code sets.
 286
 287 For example, ISO 3166 assigns one code to the country "United States
 288 Minor Outlying Islands", but the FIPS 10 codes give different codes
 289 to different islands (Baker Island, Howland Island, etc.).
 290
 291 This may cause some confusion... I've done the best that I could do
 292 to minimize it.
 293
 294 =item B<Non-ASCII characters not supported>
 295
 296 Currently all names must be all ASCII. I plan on relaxing that
 297 limitation in the future.
 298
 299 =back
 300
 301 =head1 SEE ALSO
 302
 303 Locale::Codes
 304
 305 =head1 AUTHOR
 306
 307 See Locale::Codes for full author history.
 308
 309 Currently maintained by Sullivan Beck (sbeck@cpan.org).
 310
 311 =head1 COPYRIGHT
 312
 313    Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
 314    Copyright (c) 2001-2010 Neil Bowers
 315    Copyright (c) 2010-2013 Sullivan Beck
 316
 317 This module is free software; you can redistribute it and/or
 318 modify it under the same terms as Perl itself.
 319
 320 =cut