Update Unicode-Collate to CPAN version 0.86
[perl.git] / cpan / Unicode-Collate / Collate / Locale.pm
1 package Unicode::Collate::Locale;
2
3 use strict;
4 use Carp;
5 use base qw(Unicode::Collate);
6
7 our $VERSION = '0.86';
8
9 use File::Spec;
10
11 (my $ModPath = $INC{'Unicode/Collate/Locale.pm'}) =~ s/\.pm$//;
12 my $PL_EXT  = '.pl';
13
14 my %LocaleFile = map { ($_, $_) } qw(
15    af ar as az be bg bn ca cs cy da eo es et fa fi fil fo fr
16    gu ha haw hi hr hu hy ig is ja kk kl kn ko kok ln lt lv
17    mk ml mr mt nb nn nso om or pa pl ro ru sa se si sk sl sq
18    sr sv ta te th tn to tr uk ur vi wae wo yo zh
19 );
20    $LocaleFile{'default'} = '';
21 # aliases
22    $LocaleFile{'bs'}      = 'hr';
23    $LocaleFile{'sr_Latn'} = 'hr';
24 # short file names
25    $LocaleFile{'de__phonebook'}   = 'de_phone';
26    $LocaleFile{'es__traditional'} = 'es_trad';
27    $LocaleFile{'fi__phonebook'}   = 'fi_phone';
28    $LocaleFile{'si__dictionary'}  = 'si_dict';
29    $LocaleFile{'sv__reformed'}    = 'sv_refo';
30    $LocaleFile{'zh__big5han'}     = 'zh_big5';
31    $LocaleFile{'zh__gb2312han'}   = 'zh_gb';
32    $LocaleFile{'zh__pinyin'}      = 'zh_pin';
33    $LocaleFile{'zh__stroke'}      = 'zh_strk';
34
35 my %TypeAlias = qw(
36     phone     phonebook
37     phonebk   phonebook
38     dict      dictionary
39     reform    reformed
40     trad      traditional
41     big5      big5han
42     gb2312    gb2312han
43 );
44
45 sub _locale {
46     my $locale = shift;
47     if ($locale) {
48         $locale = lc $locale;
49         $locale =~ tr/\-\ \./_/;
50         $locale =~ s/_([0-9a-z]+)\z/$TypeAlias{$1} ?
51                                   "_$TypeAlias{$1}" : "_$1"/e;
52         $LocaleFile{$locale} and return $locale;
53
54         my @code = split /_/, $locale;
55         my $lan = shift @code;
56         my $scr = @code && length $code[0] == 4 ? ucfirst shift @code : '';
57         my $reg = @code && length $code[0] <  4 ? uc      shift @code : '';
58         my $var = @code                         ?         shift @code : '';
59
60         my @list;
61         push @list, (
62             "${lan}_${scr}_${reg}_$var",
63             "${lan}_${scr}__$var", # empty $scr should not be ${lan}__$var.
64             "${lan}_${reg}_$var",  # empty $reg may be ${lan}__$var.
65             "${lan}__$var",
66         ) if $var ne '';
67         push @list, (
68             "${lan}_${scr}_${reg}",
69             "${lan}_${scr}",
70             "${lan}_${reg}",
71              ${lan},
72         );
73         for my $loc (@list) {
74             $LocaleFile{$loc} and return $loc;
75         }
76     }
77     return 'default';
78 }
79
80 sub getlocale {
81     return shift->{accepted_locale};
82 }
83
84 sub _fetchpl {
85     my $accepted = shift;
86     my $f = $LocaleFile{$accepted};
87     return if !$f;
88     $f .= $PL_EXT;
89     my $path = File::Spec->catfile($ModPath, $f);
90     my $h = do $path;
91     croak "Unicode/Collate/Locale/$f can't be found" if !$h;
92     return $h;
93 }
94
95 sub new {
96     my $class = shift;
97     my %hash = @_;
98     $hash{accepted_locale} = _locale($hash{locale});
99
100     if (exists $hash{table}) {
101         croak "your table can't be used with Unicode::Collate::Locale";
102     }
103
104     my $href = _fetchpl($hash{accepted_locale});
105     while (my($k,$v) = each %$href) {
106         if (exists $hash{$k}) {
107             croak "$k is reserved by $hash{locale}, can't be overwritten";
108         }
109         $hash{$k} = $v;
110     }
111     return $class->SUPER::new(%hash);
112 }
113
114 1;
115 __END__
116
117 MEMORANDA for developing
118
119 locale          based CLDR
120 ----------------------------------------------------------------------------
121 af              2.0 = 1.8.1
122 ar              2.0
123 as              2.0 = 1.8.1
124 az              2.0 = 1.8.1 (type="standard")
125 be              2.0
126 bg              2.0
127 bn              2.0.1 (type="standard")
128 bs              2.0 (alias source="hr")
129 ca              2.0 = 1.8.1 (alt="proposed" type="standard")
130 cs              2.0 = 1.8.1 (type="standard")
131 cy              2.0 = 1.8.1
132 da              2.0 = 1.8.1 (type="standard") [modify aA to pass CLDR tests]
133 de__phonebook   2.0 (type="phonebook")
134 eo              2.0 = 1.8.1
135 es              2.0 (type="standard")
136 es__traditional 2.0 = 1.8.1 (type="traditional")
137 et              2.0 = 1.8.1
138 fa              2.0 = 1.8.1
139 fi              2.0 = 1.8.1 (type="standard" alt="proposed")
140 fi__phonebook   2.0 = 1.8.1 (type="phonebook")
141 fil             2.0 (type="standard") = 1.8.1
142 fo              2.0 = 1.8.1 (alt="proposed" type="standard")
143 fr              2.0 (fr_CA, backwards="on")
144 gu              2.0 (type="standard")
145 ha              2.0
146 haw             2.0 = 1.8.1
147 hi              2.0 (type="standard")
148 hr              2.0 (type="standard")
149 hu              2.0 = 1.8.1 (alt="proposed" type="standard")
150 hy              2.0 = 1.8.1
151 ig              2.0 = 1.8.1
152 is              2.0 = 1.8.1 (type="standard")
153 ja              2.0 = 1.8.1 (type="standard")
154 kk              2.0
155 kl              2.0 = 1.8.1 (type="standard")
156 kn              2.0 (type="standard")
157 ko              2.0 = 1.8.1 (type="standard")
158 kok             2.0 = 1.8.1
159 ln              2.0 (type="standard") = 1.8.1
160 lt              2.0
161 lv              2.0 (type="standard") = 1.8.1
162 mk              2.0
163 ml              2.0
164 mr              2.0 = 1.8.1
165 mt              2.0
166 nb              2.0 (type="standard")
167 nn              2.0 (type="standard")
168 nso             2.0 = 1.8.1
169 om              2.0 = 1.8.1
170 or              2.0
171 pa              2.0 = 1.8.1
172 pl              2.0 = 1.8.1
173 ro              2.0 (type="standard")
174 ru              2.0
175 sa              1.8.1 (type="standard" alt="proposed") [currently in /seed]
176 se              2.0 = 1.8.1 (type="standard")
177 si              2.0 (type="standard")
178 si__dictionary  2.0 (type="dictionary")
179 sk              2.0 (type="standard")
180 sl              2.0 = 1.8.1 (type="standard" alt="proposed")
181 sq              2.0 = 1.8.1 (alt="proposed" type="standard")
182 sr              2.0 (type="standard")
183 sr_Latn         2.0 = 1.8.1 (alias source="hr")
184 sv              2.0 (type="standard")
185 sv__reformed    2.0 = 1.8.1 (type="reformed")
186 ta              2.0
187 te              2.0
188 th              2.0 (type="standard")
189 tn              2.0 = 1.8.1
190 to              2.0 = 1.8.1 (type="standard" alt="proposed")
191 tr              2.0 = 1.8.1 (type="standard")
192 uk              2.0
193 ur              2.0
194 vi              2.0 = 1.8.1
195 wae             2.0
196 wo              1.8.1 [currently in /seed]
197 yo              2.0 = 1.8.1
198 zh              2.0 = 1.8.1 (type="standard")
199 zh__big5han     2.0 = 1.8.1 (type="big5han")
200 zh__gb2312han   2.0 = 1.8.1 (type="gb2312han")
201 zh__pinyin      2.0 (type='pinyin' alt='short')
202 zh__stroke      2.0 = 1.9.1 (type='stroke' alt='short')
203 ----------------------------------------------------------------------------
204
205 =head1 NAME
206
207 Unicode::Collate::Locale - Linguistic tailoring for DUCET via Unicode::Collate
208
209 =head1 SYNOPSIS
210
211   use Unicode::Collate::Locale;
212
213   #construct
214   $Collator = Unicode::Collate::Locale->
215       new(locale => $locale_name, %tailoring);
216
217   #sort
218   @sorted = $Collator->sort(@not_sorted);
219
220   #compare
221   $result = $Collator->cmp($a, $b); # returns 1, 0, or -1.
222
223 B<Note:> Strings in C<@not_sorted>, C<$a> and C<$b> are interpreted
224 according to Perl's Unicode support. See L<perlunicode>,
225 L<perluniintro>, L<perlunitut>, L<perlunifaq>, L<utf8>.
226 Otherwise you can use C<preprocess> (cf. C<Unicode::Collate>)
227 or should decode them before.
228
229 =head1 DESCRIPTION
230
231 This module provides linguistic tailoring for it
232 taking advantage of C<Unicode::Collate>.
233
234 =head2 Constructor
235
236 The C<new> method returns a collator object.
237
238 A parameter list for the constructor is a hash, which can include
239 a special key C<locale> and its value (case-insensitive) standing
240 for a Unicode base language code (two or three-letter).
241 For example, C<Unicode::Collate::Locale-E<gt>new(locale =E<gt> 'FR')>
242 returns a collator tailored for French.
243
244 C<$locale_name> may be suffixed with a Unicode script code (four-letter),
245 a Unicode region code, a Unicode language variant code. These codes are
246 case-insensitive, and separated with C<'_'> or C<'-'>.
247 E.g. C<en_US> for English in USA,
248 C<az_Cyrl> for Azerbaijani in the Cyrillic script,
249 C<es_ES_traditional> for Spanish in Spain (Traditional).
250
251 If C<$locale_name> is not available,
252 fallback is selected in the following order:
253
254     1. language with a variant code
255     2. language with a script code
256     3. language with a region code
257     4. language
258     5. default
259
260 Tailoring tags provided by C<Unicode::Collate> are allowed as long as
261 they are not used for C<locale> support.  Esp. the C<table> tag
262 is always untailorable, since it is reserved for DUCET.
263
264 E.g. a collator for French, which ignores diacritics and case difference
265 (i.e. level 1), with reversed case ordering and no normalization.
266
267     Unicode::Collate::Locale->new(
268         level => 1,
269         locale => 'fr',
270         upper_before_lower => 1,
271         normalization => undef
272     )
273
274 Overriding a behavior already tailored by C<locale> is disallowed
275 if such a tailoring is passed to C<new()>.
276
277     Unicode::Collate::Locale->new(
278         locale => 'da',
279         upper_before_lower => 0, # causes error as reserved by 'da'
280     )
281
282 However C<change()> inherited from C<Unicode::Collate> allows
283 such a tailoring that is reserved by C<locale>. Examples:
284
285     new(locale => 'ca')->change(backwards => undef)
286     new(locale => 'da')->change(upper_before_lower => 0)
287     new(locale => 'ja')->change(overrideCJK => undef)
288
289 =head2 Methods
290
291 C<Unicode::Collate::Locale> is a subclass of C<Unicode::Collate>
292 and methods other than C<new> are inherited from C<Unicode::Collate>.
293
294 Here is a list of additional methods:
295
296 =over 4
297
298 =item C<$Collator-E<gt>getlocale>
299
300 Returns a language code accepted and used actually on collation.
301 If linguistic tailoring is not provided for a language code you passed
302 (intensionally for some languages, or due to the incomplete implementation),
303 this method returns a string C<'default'> meaning no special tailoring.
304
305 =back
306
307 =head2 A list of tailorable locales
308
309       locale name       description
310     --------------------------------------------------------------
311       af                Afrikaans
312       ar                Arabic
313       as                Assamese
314       az                Azerbaijani (Azeri)
315       be                Belarusian
316       bg                Bulgarian
317       bn                Bengali
318       bs                Bosnian
319       ca                Catalan
320       cs                Czech
321       cy                Welsh
322       da                Danish
323       de__phonebook     German (umlaut as 'ae', 'oe', 'ue')
324       eo                Esperanto
325       es                Spanish
326       es__traditional   Spanish ('ch' and 'll' as a grapheme)
327       et                Estonian
328       fa                Persian
329       fi                Finnish (v and w are primary equal)
330       fi__phonebook     Finnish (v and w as separate characters)
331       fil               Filipino
332       fo                Faroese
333       fr                French
334       gu                Gujarati
335       ha                Hausa
336       haw               Hawaiian
337       hi                Hindi
338       hr                Croatian
339       hu                Hungarian
340       hy                Armenian
341       ig                Igbo
342       is                Icelandic
343       ja                Japanese [1]
344       kk                Kazakh
345       kl                Kalaallisut
346       kn                Kannada
347       ko                Korean [2]
348       kok               Konkani
349       ln                Lingala
350       lt                Lithuanian
351       lv                Latvian
352       mk                Macedonian
353       ml                Malayalam
354       mr                Marathi
355       mt                Maltese
356       nb                Norwegian Bokmal
357       nn                Norwegian Nynorsk
358       nso               Northern Sotho
359       om                Oromo
360       or                Oriya
361       pa                Punjabi
362       pl                Polish
363       ro                Romanian
364       ru                Russian
365       sa                Sanskrit
366       se                Northern Sami
367       si                Sinhala
368       si__dictionary    Sinhala (U+0DA5 = U+0DA2,0DCA,0DA4)
369       sk                Slovak
370       sl                Slovenian
371       sq                Albanian
372       sr                Serbian
373       sr_Latn           Serbian in Latin (tailored as Croatian)
374       sv                Swedish (v and w are primary equal)
375       sv__reformed      Swedish (v and w as separate characters)
376       ta                Tamil
377       te                Telugu
378       th                Thai
379       tn                Tswana
380       to                Tonga
381       tr                Turkish
382       uk                Ukrainian
383       ur                Urdu
384       vi                Vietnamese
385       wae               Walser
386       wo                Wolof
387       yo                Yoruba
388       zh                Chinese
389       zh__big5han       Chinese (ideographs: big5 order)
390       zh__gb2312han     Chinese (ideographs: GB-2312 order)
391       zh__pinyin        Chinese (ideographs: pinyin order) [3]
392       zh__stroke        Chinese (ideographs: stroke order) [3]
393     --------------------------------------------------------------
394
395 Locales according to the default UCA rules include
396 chr (Cherokee),
397 de (German),
398 en (English),
399 ga (Irish),
400 id (Indonesian),
401 it (Italian),
402 ka (Georgian),
403 ms (Malay),
404 nl (Dutch),
405 pt (Portuguese),
406 st (Southern Sotho),
407 sw (Swahili),
408 xh (Xhosa),
409 zu (Zulu).
410
411 B<Note>
412
413 [1] ja: Ideographs are sorted in JIS X 0208 order.
414 Fullwidth and halfwidth forms are identical to their normal form.
415 The difference between hiragana and katakana is at the 4th level,
416 the comparison also requires C<(variable =E<gt> 'Non-ignorable')>,
417 and then C<katakana_before_hiragana> has no effect.
418
419 [2] ko: Plenty of ideographs are sorted by their reading. Such
420 an ideograph is primary (level 1) equal to, and secondary (level 2)
421 greater than, the corresponding hangul syllable.
422
423 [3] zh__pinyin and zh__stroke: implemented alt='short', where
424 a smaller number of ideographs are tailored.
425
426 =head1 INSTALL
427
428 Installation of C<Unicode::Collate::Locale> requires F<Collate/Locale.pm>,
429 F<Collate/Locale/*.pm>, F<Collate/CJK/*.pm> and F<Collate/allkeys.txt>.
430 On building, C<Unicode::Collate::Locale> doesn't require any of F<data/*.txt>,
431 F<gendata/*>, and F<mklocale>.
432 Tests for C<Unicode::Collate::Locale> are named F<t/loc_*.t>.
433
434 =head1 CAVEAT
435
436 =over 4
437
438 =item tailoring is not maximum
439
440 Even if a certain letter is tailored, its equivalent would not always
441 tailored as well as it. For example, even though W is tailored,
442 fullwidth W (C<U+FF37>), W with acute (C<U+1E82>), etc. are not
443 tailored. The result may depend on whether source strings are
444 normalized or not, and whether decomposed or composed.
445 Thus C<(normalization =E<gt> undef)> is less preferred.
446
447 =back
448
449 =head1 AUTHOR
450
451 The Unicode::Collate::Locale module for perl was written
452 by SADAHIRO Tomoyuki, <SADAHIRO@cpan.org>.
453 This module is Copyright(C) 2004-2011, SADAHIRO Tomoyuki. Japan.
454 All rights reserved.
455
456 This module is free software; you can redistribute it and/or
457 modify it under the same terms as Perl itself.
458
459 =head1 SEE ALSO
460
461 =over 4
462
463 =item Unicode Collation Algorithm - UTS #10
464
465 L<http://www.unicode.org/reports/tr10/>
466
467 =item The Default Unicode Collation Element Table (DUCET)
468
469 L<http://www.unicode.org/Public/UCA/latest/allkeys.txt>
470
471 =item Unicode Locale Data Markup Language (LDML) - UTS #35
472
473 L<http://www.unicode.org/reports/tr35/>
474
475 =item CLDR - Unicode Common Locale Data Repository
476
477 L<http://cldr.unicode.org/>
478
479 =item L<Unicode::Collate>
480
481 =item L<Unicode::Normalize>
482
483 =back
484
485 =cut