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