Update Unicode-Collate to CPAN version 0.65
[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.65';
8
9 use File::Spec;
10
11 (my $ModPath = $INC{'Unicode/Collate/Locale.pm'}) =~ s/\.pm$//;
12 my $KeyPath = File::Spec->catfile('allkeys.txt');
13 my $PL_EXT  = '.pl';
14
15 my %LocaleFile = map { ($_, $_) } qw(
16    af ar az ca cs cy da eo es et fi fil fo fr ha haw
17    hr hu hy ig is ja kk kl lt lv mt nb nn nso om pl ro ru
18    se sk sl sq sv sw tn to tr uk vi wo yo zh
19 );
20    $LocaleFile{'default'}         = '';
21    $LocaleFile{'de__phonebook'}   = 'de_phone';
22    $LocaleFile{'es__traditional'} = 'es_trad';
23    $LocaleFile{'be'} = 'ru';
24    $LocaleFile{'bg'} = 'ru';
25    $LocaleFile{'mk'} = 'ru';
26    $LocaleFile{'sr'} = 'ru';
27    $LocaleFile{'zh__big5han'}   = 'zh_big5';
28    $LocaleFile{'zh__gb2312han'} = 'zh_gb';
29    $LocaleFile{'zh__pinyin'}    = 'zh_pin';
30    $LocaleFile{'zh__stroke'}    = 'zh_strk';
31
32 sub _locale {
33     my $locale = shift;
34     if ($locale) {
35         $locale = lc $locale;
36         $locale =~ tr/\-\ \./_/;
37         $locale =~ s/_phone(?:bk)?\z/_phonebook/;
38         $locale =~ s/_trad\z/_traditional/;
39         $locale =~ s/_big5\z/_big5han/;
40         $locale =~ s/_gb2312\z/_gb2312han/;
41         $LocaleFile{$locale} and return $locale;
42
43         my ($l,$t,$v) = split(/_/, $locale.'__');
44         for my $loc ("${l}_${t}_$v", "${l}_$t", "${l}__$v", "${l}__$t", $l) {
45             $LocaleFile{$loc} and return $loc;
46         }
47     }
48     return 'default';
49 }
50
51 sub getlocale {
52     return shift->{accepted_locale};
53 }
54
55 sub _fetchpl {
56     my $accepted = shift;
57     my $f = $LocaleFile{$accepted};
58     return if !$f;
59     $f .= $PL_EXT;
60     my $path = File::Spec->catfile($ModPath, $f);
61     my $h = do $path;
62     croak "Unicode/Collate/Locale/$f can't be found" if !$h;
63     return $h;
64 }
65
66 sub new {
67     my $class = shift;
68     my %hash = @_;
69     $hash{accepted_locale} = _locale($hash{locale});
70
71     if (exists $hash{table}) {
72         croak "your table can't be used with Unicode::Collate::Locale";
73     }
74     $hash{table} = $KeyPath;
75
76     my $href = _fetchpl($hash{accepted_locale});
77     while (my($k,$v) = each %$href) {
78         if (exists $hash{$k}) {
79             croak "$k is reserved by $hash{locale}, can't be overwritten";
80         }
81         $hash{$k} = $v;
82     }
83     return $class->SUPER::new(%hash);
84 }
85
86 1;
87 __END__
88
89 =head1 NAME
90
91 Unicode::Collate::Locale - Linguistic tailoring for DUCET via Unicode::Collate
92
93 =head1 SYNOPSIS
94
95   use Unicode::Collate::Locale;
96
97   #construct
98   $Collator = Unicode::Collate::Locale->
99       new(locale => $locale_name, %tailoring);
100
101   #sort
102   @sorted = $Collator->sort(@not_sorted);
103
104   #compare
105   $result = $Collator->cmp($a, $b); # returns 1, 0, or -1.
106
107 B<Note:> Strings in C<@not_sorted>, C<$a> and C<$b> are interpreted
108 according to Perl's Unicode support. See L<perlunicode>,
109 L<perluniintro>, L<perlunitut>, L<perlunifaq>, L<utf8>.
110 Otherwise you can use C<preprocess> (cf. C<Unicode::Collate>)
111 or should decode them before.
112
113 =head1 DESCRIPTION
114
115 This module provides linguistic tailoring for it
116 taking advantage of C<Unicode::Collate>.
117
118 =head2 Constructor
119
120 The C<new> method returns a collator object.
121
122 A parameter list for the constructor is a hash, which can include
123 a special key C<'locale'> and its value (case-insensitive) standing
124 for a two-letter language code (ISO-639) like C<'en'> for English.
125 For example, C<Unicode::Collate::Locale-E<gt>new(locale =E<gt> 'FR')>
126 returns a collator tailored for French.
127
128 C<$locale_name> may be suffixed with a territory(country)
129 code or a variant code, which are separated with C<'_'>.
130 E.g. C<en_US> for English in USA,
131 C<es_ES_traditional> for Spanish in Spain (Traditional),
132
133 If C<$localename> is not defined,
134 fallback is selected in the following order:
135
136     1. language_territory_variant
137     2. language_territory
138     3. language__variant
139     4. language
140     5. default
141
142 Tailoring tags provided by C<Unicode::Collate> are allowed
143 as long as they are not used for C<'locale'> support.
144 Esp. the C<table> tag is always untailorable
145 since it is reserved for DUCET.
146
147 E.g. a collator for French, which ignores diacritics and case difference
148 (i.e. level 1), with reversed case ordering and no normalization.
149
150     Unicode::Collate::Locale->new(
151         level => 1,
152         locale => 'fr',
153         upper_before_lower => 1,
154         normalization => undef
155     )
156
157 =head2 Methods
158
159 C<Unicode::Collate::Locale> is a subclass of C<Unicode::Collate>
160 and methods other than C<new> are inherited from C<Unicode::Collate>.
161
162 Here is a list of additional methods:
163
164 =over 4
165
166 =item C<$Collator-E<gt>getlocale>
167
168 Returns a language code accepted and used actually on collation.
169 If linguistic tailoring is not provided for a language code you passed
170 (intensionally for some languages, or due to the incomplete implementation),
171 this method returns a string C<'default'> meaning no special tailoring.
172
173 =back
174
175 =head2 A list of tailorable locales
176
177       locale name       description
178     ----------------------------------------------------------
179       af                Afrikaans
180       ar                Arabic
181       az                Azerbaijani (Azeri)
182       be                Belarusian
183       bg                Bulgarian
184       ca                Catalan
185       cs                Czech
186       cy                Welsh
187       da                Danish
188       de__phonebook     German (umlaut as 'ae', 'oe', 'ue')
189       eo                Esperanto
190       es                Spanish
191       es__traditional   Spanish ('ch' and 'll' as a grapheme)
192       et                Estonian
193       fi                Finnish
194       fil               Filipino
195       fo                Faroese
196       fr                French
197       ha                Hausa
198       haw               Hawaiian
199       hr                Croatian
200       hu                Hungarian
201       hy                Armenian
202       ig                Igbo
203       is                Icelandic
204       ja                Japanese [1]
205       kk                Kazakh
206       kl                Kalaallisut
207       lt                Lithuanian
208       lv                Latvian
209       mk                Macedonian
210       mt                Maltese
211       nb                Norwegian Bokmal
212       nn                Norwegian Nynorsk
213       nso               Northern Sotho
214       om                Oromo
215       pl                Polish
216       ro                Romanian
217       ru                Russian
218       se                Northern Sami
219       sk                Slovak
220       sl                Slovenian
221       sq                Albanian
222       sr                Serbian
223       sv                Swedish
224       sw                Swahili
225       tn                Tswana
226       to                Tonga
227       tr                Turkish
228       uk                Ukrainian
229       vi                Vietnamese
230       wo                Wolof
231       yo                Yoruba
232       zh                Chinese
233       zh__big5han       Chinese (ideographs: big5 order)
234       zh__gb2312han     Chinese (ideographs: GB-2312 order)
235       zh__pinyin        Chinese (ideographs: pinyin order)
236       zh__stroke        Chinese (ideographs: stroke order)
237     ----------------------------------------------------------
238
239 Locales according to the default UCA rules include
240 de (German),
241 en (English),
242 ga (Irish),
243 id (Indonesian),
244 it (Italian),
245 ka (Georgian),
246 ln (Lingala),
247 ms (Malay),
248 nl (Dutch),
249 pt (Portuguese),
250 st (Southern Sotho),
251 xh (Xhosa),
252 zu (Zulu).
253
254 B<Note>
255
256 [1] ja: Ideographs are sorted in JIS X 0208 order.
257 Fullwidth and halfwidth forms are identical to their normal form.
258 The difference between hiragana and katakana is at the 4th level,
259 the comparison also requires C<(variable =E<gt> 'Non-ignorable')>,
260 and then C<katakana_before_hiragana> has no effect.
261
262 =head1 INSTALL
263
264 Installation of C<Unicode::Collate::Locale> requires F<Collate/Locale.pm>,
265 F<Collate/Locale/*.pm>, F<Collate/CJK/*.pm> and F<Collate/allkeys.txt>.
266 On building, C<Unicode::Collate::Locale> doesn't require any of F<data/*.txt>,
267 F<gendata/*>, and F<mklocale>.
268 Tests for C<Unicode::Collate::Locale> are named F<t/loc_*.t>.
269
270 =head1 CAVEAT
271
272 =over 4
273
274 =item tailoring is not maximum
275
276 Even if a certain letter is tailored, its equivalent would not always
277 tailored as well as it. For example, even though W is tailored,
278 fullwidth W (C<U+FF37>), W with acute (C<U+1E82>), etc. are not
279 tailored. The result may depend on whether source strings are
280 normalized or not, and whether decomposed or composed.
281 Thus C<(normalization =E<gt> undef> is less preferred.
282
283 =back
284
285 =head1 AUTHOR
286
287 The Unicode::Collate::Locale module for perl was written
288 by SADAHIRO Tomoyuki, <SADAHIRO@cpan.org>.
289 This module is Copyright(C) 2004-2010, SADAHIRO Tomoyuki. Japan.
290 All rights reserved.
291
292 This module is free software; you can redistribute it and/or
293 modify it under the same terms as Perl itself.
294
295 =head1 SEE ALSO
296
297 =over 4
298
299 =item Unicode Collation Algorithm - UTS #10
300
301 L<http://www.unicode.org/reports/tr10/>
302
303 =item The Default Unicode Collation Element Table (DUCET)
304
305 L<http://www.unicode.org/Public/UCA/latest/allkeys.txt>
306
307 =item Unicode Locale Data Markup Language (LDML) - UTS #35
308
309 L<http://www.unicode.org/reports/tr35/>
310
311 =item CLDR - Unicode Common Locale Data Repository
312
313 L<http://cldr.unicode.org/>
314
315 =item L<Unicode::Collate>
316
317 =item L<Unicode::Normalize>
318
319 =back
320
321 =cut