This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
bbd6e1f498e3d8125621717675c11e0e3df00a71
[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.63';
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 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   $Collator = Unicode::Collate::Locale->
92       new(locale => $locale_name, %tailoring);
93
94   @sorted = $Collator->sort(@not_sorted);
95
96 =head1 DESCRIPTION
97
98 This module provides linguistic tailoring for it
99 taking advantage of C<Unicode::Collate>.
100
101 =head2 Constructor
102
103 The C<new> method returns a collator object.
104
105 A parameter list for the constructor is a hash, which can include
106 a special key C<'locale'> and its value (case-insensitive) standing
107 for a two-letter language code (ISO-639) like C<'en'> for English.
108 For example, C<Unicode::Collate::Locale-E<gt>new(locale =E<gt> 'FR')>
109 returns a collator tailored for French.
110
111 C<$locale_name> may be suffixed with a territory(country)
112 code or a variant code, which are separated with C<'_'>.
113 E.g. C<en_US> for English in USA,
114 C<es_ES_traditional> for Spanish in Spain (Traditional),
115
116 If C<$localename> is not defined,
117 fallback is selected in the following order:
118
119     1. language_territory_variant
120     2. language_territory
121     3. language__variant
122     4. language
123     5. default
124
125 Tailoring tags provided by C<Unicode::Collate> are allowed
126 as long as they are not used for C<'locale'> support.
127 Esp. the C<table> tag is always untailorable
128 since it is reserved for DUCET.
129
130 E.g. a collator for French, which ignores diacritics and case difference
131 (i.e. level 1), with reversed case ordering and no normalization.
132
133     Unicode::Collate::Locale->new(
134         level => 1,
135         locale => 'fr',
136         upper_before_lower => 1,
137         normalization => undef
138     )
139
140 =head2 Methods
141
142 C<Unicode::Collate::Locale> is a subclass of C<Unicode::Collate>
143 and methods other than C<new> are inherited from C<Unicode::Collate>.
144
145 Here is a list of additional methods:
146
147 =over 4
148
149 =item C<$Collator-E<gt>getlocale>
150
151 Returns a language code accepted and used actually on collation.
152 If linguistic tailoring is not provided for a language code you passed
153 (intensionally for some languages, or due to the incomplete implementation),
154 this method returns a string C<'default'> meaning no special tailoring.
155
156 =back
157
158 =head2 A list of tailorable locales
159
160       locale name       description
161     ----------------------------------------------------------
162       af                Afrikaans
163       ar                Arabic
164       az                Azerbaijani (Azeri)
165       be                Belarusian
166       bg                Bulgarian
167       ca                Catalan
168       cs                Czech
169       cy                Welsh
170       da                Danish
171       de__phonebook     German (umlaut as 'ae', 'oe', 'ue')
172       eo                Esperanto
173       es                Spanish
174       es__traditional   Spanish ('ch' and 'll' as a grapheme)
175       et                Estonian
176       fi                Finnish
177       fil               Filipino
178       fo                Faroese
179       fr                French
180       ha                Hausa
181       haw               Hawaiian
182       hr                Croatian
183       hu                Hungarian
184       hy                Armenian
185       ig                Igbo
186       is                Icelandic
187       kk                Kazakh
188       kl                Kalaallisut
189       lt                Lithuanian
190       lv                Latvian
191       mk                Macedonian
192       mt                Maltese
193       nb                Norwegian Bokmal
194       nn                Norwegian Nynorsk
195       nso               Northern Sotho
196       om                Oromo
197       pl                Polish
198       ro                Romanian
199       ru                Russian
200       se                Northern Sami
201       sk                Slovak
202       sl                Slovenian
203       sq                Albanian
204       sr                Serbian
205       sv                Swedish
206       sw                Swahili
207       tn                Tswana
208       to                Tonga
209       tr                Turkish
210       uk                Ukrainian
211       vi                Vietnamese
212       wo                Wolof
213       yo                Yoruba
214     ----------------------------------------------------------
215
216 Locales according to default UCA rules include:
217 de (German),
218 en (English),
219 ga (Irish),
220 id (Indonesian),
221 it (Italian),
222 ka (Georgian),
223 ln (Lingala),
224 ms (Malay),
225 nl (Dutch),
226 pt (Portuguese),
227 st (Southern Sotho),
228 xh (Xhosa),
229 zu (Zulu).
230
231 =head1 INSTALL
232
233 Installation of Unicode::Collate::Locale requires F<Collate/Locale.pm>,
234 F<Collate/Locale/*.pm> and F<Collate/allkeys.txt>.  On building,
235 Unicode::Collate::Locale doesn't require F<data/*.txt> and F<mklocale>.
236 Tests for Unicode::Collate::Locale are named F<t/loc_*.t>.
237
238 =head1 CAVEAT
239
240 =over 4
241
242 =item tailoring is not maximum
243
244 If a certain letter is tailored, its equivalents are not always
245 tailored as well as it. For example, even though W is tailored,
246 fullwidth W (C<U+FF37>), W with acute (C<U+1E82>), etc. are not
247 tailored. The result may depend on whether source strings are
248 normalized or not, and whether decomposed or composed.
249 Thus C<(normalization =E<gt> undef> is less preferred.
250
251 =back
252
253 =head1 AUTHOR
254
255 The Unicode::Collate::Locale module for perl was written
256 by SADAHIRO Tomoyuki, <SADAHIRO@cpan.org>.
257 This module is Copyright(C) 2004-2010, SADAHIRO Tomoyuki. Japan.
258 All rights reserved.
259
260 This module is free software; you can redistribute it and/or
261 modify it under the same terms as Perl itself.
262
263 =head1 SEE ALSO
264
265 =over 4
266
267 =item Unicode Collation Algorithm - UTS #10
268
269 L<http://www.unicode.org/reports/tr10/>
270
271 =item The Default Unicode Collation Element Table (DUCET)
272
273 L<http://www.unicode.org/Public/UCA/latest/allkeys.txt>
274
275 =item Unicode Locale Data Markup Language (LDML) - UTS #35
276
277 L<http://www.unicode.org/reports/tr35/>
278
279 =item CLDR - Unicode Common Locale Data Repository
280
281 L<http://cldr.unicode.org/>
282
283 =item L<Unicode::Collate>
284
285 =item L<Unicode::Normalize>
286
287 =back
288
289 =cut