1Locale::Codes::API(3) User Contributed Perl DocumentationLocale::Codes::API(3)
2
3
4

NAME

6       Locale::Codes::API - a description of the callable function in each
7       module
8

DESCRIPTION

10       Although there are several modules in the Locale-Codes distribution,
11       all of them (as of version 3.10) use exactly the same API.  As a matter
12       of fact, each of the main callable modules are just wrappers around a
13       central module which does all the real work.
14

ROUTINES

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
21       module contains a function "code2XXX" where XXX refers to the type of
22       data.  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
39       3166-1, the code 'fi' is used to refer to the country Finland. CODE is
40       always case insensitive (though when a code is returned, it will always
41       be in the case as used in the standard), so 'fi', 'FI', and 'Fi' would
42       all 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       code2XXX ( CODE [,CODESET] [,'retired'] )
58           These functions take a code and returns a string which contains the
59           name of the element identified.  If the code is not a valid code in
60           the CODESET specified then "undef" will be returned.
61
62           The name of the element is the name as specified in the standard,
63           and as a result, different variations of an element name may be
64           returned for different values of CODESET.
65
66           For example, the alpha-2 country code set defines the two-letter
67           code "bo" to be "Bolivia, Plurinational State of", whereas the
68           alpha-3 code set defines the code 'bol' to be the country "Bolivia
69           (Plurinational State of)". So:
70
71              code2country('bo',LOCALE_CODE_ALPHA_2);
72                 => 'Bolivia, Plurinational State of'
73
74              code2country('bol',LOCALE_CODE_ALPHA_3);
75                 => 'Bolivia (Plurinational State of)'
76
77           By default, only active codes will be used, but if the string
78           'retired' is passed in as an argument, both active and retired
79           codes will be examined.
80
81       XXX2code ( NAME [,CODESET] [,'retired'] )
82           These functions takes the name of an element (or any of it's
83           aliases) and returns the code that corresponds to it, if it exists.
84           If NAME could not be identified as the name of one of the elements,
85           then "undef" will be returned.
86
87           The name is not case sensitive. Also, any known variation of a name
88           may be passed in.
89
90           For example, even though the country name returned using
91           LOCALE_CODE_ALPHA_2 and LOCALE_CODE_ALPHA_3 country codes for
92           Bolivia is different, either country name may be passed in since
93           for each code set, in addition to the alias 'Bolivia'. So:
94
95              country2code('Bolivia, Plurinational State of',
96                           LOCALE_CODE_ALPHA_2);
97                 => bo
98
99              country2code('Bolivia (Plurinational State of)',
100                           LOCALE_CODE_ALPHA_2);
101                 => bo
102
103              country2code('Bolivia',LOCALE_CODE_ALPHA_2);
104                 => bo
105
106           By default, only active names will be used, but if the string
107           'retired' is passed in as an argument, both active and retired
108           names will be examined.
109
110       XXX_code2code ( CODE ,CODESET ,CODESET2 )
111           These functions takes a code from one code set, and returns the
112           corresponding code from another code set. CODE must exists in the
113           code set specified by CODESET and must have a corresponding code in
114           the code set specified by CODESET2 or "undef" will be returned.
115
116           Both CODESETs must be explicitly entered.
117
118              country_code2code('fin', LOCALE_CODE_ALPHA_3,
119                                LOCALE_CODE_ALPHA_2);
120                 => 'fi'
121
122           Note that this function does NOT support retired codes.
123
124       all_XXX_codes ( [CODESET] [,'retired'] )
125           These returns a list of all code in the code set. The codes will be
126           sorted.
127
128           By default, only active codes will be returned, but if the string
129           'retired' is passed in as an argument, both active and retired
130           codes will be returned.
131
132       all_XXX_names ( [CODESET] [,'retired'] )
133           These return a list of all elements names for which there is a
134           corresponding code in the specified code set.
135
136           The names returned are exactly as they are specified in the
137           standard, and are sorted.
138
139           Since not all elements are listed in all code sets, the list of
140           elements may differ depending on the code set specified.
141
142           By default, only active names will be returned, but if the string
143           'retired' is passed in as an argument, both active and retired
144           names will be returned.
145

SEMI-PRIVATE ROUTINES

147       Additional semi-private routines which may be used to modify the
148       internal data are also available.  Given their status, they aren't
149       exported, and so need to be called by prefixing the function name with
150       the package name.
151
152       These routines do not currently work with retired codes.
153
154       MODULE::rename_XXX  ( CODE ,NEW_NAME [,CODESET] )
155           These routines are used to change the official name of an element.
156           At that point, the name returned by the code2XXX routine would be
157           NEW_NAME instead of the name specified in the standard.
158
159           The original name will remain as an alias.
160
161           For example, the official country name for code 'gb' is 'United
162           Kingdom'.  If you want to change that, you might call:
163
164              Locale::Codes::Country::rename_country('gb', 'Great Britain');
165
166           This means that calling code2country('gb') will now return 'Great
167           Britain' instead of 'United Kingdom'.
168
169           If any error occurs, a warning is issued and 0 is returned. An
170           error occurs if CODE doesn't exist in the specified code set, or if
171           NEW_NAME is already in use but for a different element.
172
173           If the routine succeeds, 1 is returned.
174
175       MODULE::add_XXX  ( CODE ,NAME [,CODESET] )
176           These routines are used to add a new code and name to the data.
177
178           Both CODE and NAME must be unused in the data set or an error
179           occurs (though NAME may be used in a different data set).
180
181           For example, to create the fictitious country named "Duchy of Grand
182           Fenwick" with codes "gf" and "fen", use the following:
183
184              Locale::Codes::Country::add_country("fe","Duchy of Grand Fenwick",
185                                           LOCALE_CODE_ALPHA_2);
186
187              Locale::Codes::Country::add_country("fen","Duchy of Grand Fenwick",
188                                           LOCALE_CODE_ALPHA_3);
189
190           The return value is 1 on success, 0 on an error.
191
192       MODULE::delete_XXX  ( CODE [,CODESET] )
193           These routines are used to delete a code from the data.
194
195           CODE must refer to an existing code in the code set.
196
197           The return value is 1 on success, 0 on an error.
198
199       MODULE::add_XXX_alias  ( NAME ,NEW_NAME )
200           These routines are used to add a new alias to the data. They do not
201           alter the return value of the code2XXX function.
202
203           NAME must be an existing element name, and NEW_NAME must be unused
204           or an error occurs.
205
206           The return value is 1 on success, 0 on an error.
207
208       MODULE::delete_XXX_alias  ( NAME )
209           These routines are used to delete an alias from the data. Once
210           removed, the element may not be referred to by NAME.
211
212           NAME must be one of a list of at least two names that may be used
213           to specify an element. If the element may only be referred to by a
214           single name, you'll need to use the add_XXX_alias function to add a
215           new alias first, or the remove_XXX function to remove the element
216           entirely.
217
218           If the alias is used as the name in any code set, one of the other
219           names will be used instead. Predicting exactly which one will be
220           used requires you to know the order in which the standards were
221           read, which is not reliable, so you may want to use the rename_XXX
222           function to force one of the alternate names to be used.
223
224           The return value is 1 on success, 0 on an error.
225
226       MODULE::rename_XXX_code  ( CODE ,NEW_CODE [,CODESET] )
227           These routines are used to change the official code for an element.
228           At that point, the code returned by the XXX2code routine would be
229           NEW_CODE instead of the code specified in the standard.
230
231           NEW_CODE may either be a code that is not in use, or it may be an
232           alias for CODE (in which case, CODE becomes and alias and NEW_CODE
233           becomes the "real" code).
234
235           The original code is kept as an alias, so that the code2XXX
236           routines will work with either the code from the standard or the
237           new code.
238
239           However, the all_XXX_codes routine will only return the codes which
240           are considered "real" (which means that the list of codes will now
241           contain NEW_CODE, but will not contain CODE).
242
243       MODULE::add_XXX_code_alias  ( CODE ,NEW_CODE [,CODESET] )
244           These routines add an alias for the code. At that point, NEW_CODE
245           and CODE will both work in the code2XXX routines. However, the
246           XXX2code routines will still return the original code.
247
248       MODULE::delete_XXX_code_alias  ( CODE [,CODESET] )
249           These routines delete an alias for the code.
250
251           These will only work if CODE is actually an alias. If it is the
252           "real" code, it will not be deleted. You will need to use the
253           rename_XXX_code function to switch the real code with one of the
254           aliases, and then delete the alias.
255

KNOWN BUGS AND LIMITATIONS

257       Relationship between code sets
258           Because each code set uses a slightly different list of elements,
259           and they are not necessarily one-to-one, there may be some
260           confusion about the relationship between codes from different code
261           sets.
262
263           For example, ISO 3166 assigns one code to the country "United
264           States Minor Outlying Islands", but the FIPS 10 codes give
265           different codes to different islands (Baker Island, Howland Island,
266           etc.).
267
268           This may cause some confusion... I've done the best that I could do
269           to minimize it.
270
271       Non-ASCII characters not supported
272           Currently all names must be all ASCII. I plan on relaxing that
273           limitation in the future.
274

SEE ALSO

276       Locale::Codes
277

AUTHOR

279       See Locale::Codes for full author history.
280
281       Currently maintained by Sullivan Beck (sbeck@cpan.org).
282
284          Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
285          Copyright (c) 2001-2010 Neil Bowers
286          Copyright (c) 2010-2013 Sullivan Beck
287
288       This module is free software; you can redistribute it and/or modify it
289       under the same terms as Perl itself.
290
291
292
293perl v5.16.3                      2013-05-29             Locale::Codes::API(3)
Impressum