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