This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Unicode-Collate to CPAN version 0.59
[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.59';
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 az ca cs cy da eo es et fi fil fo fr ha haw
17    is kl lt lv mt nn pl ro sk sl sv sw tr wo yo
18 );
19    $LocaleFile{'default'}         = '';
20    $LocaleFile{'es__traditional'} = 'es_trad';
21    $LocaleFile{'nb'} = 'nn';
22
23 sub _locale {
24     my $locale = shift;
25     if ($locale) {
26         $locale = lc $locale;
27         $locale =~ tr/\-\ \./_/;
28         $locale =~ s/_trad\z/_traditional/;
29         $LocaleFile{$locale} and return $locale;
30
31         my ($l,$t,$v) = split(/_/, $locale.'__');
32         for my $loc ("${l}_${t}_$v", "${l}_$t", "${l}__$v", "${l}__$t", $l) {
33             $LocaleFile{$loc} and return $loc;
34         }
35     }
36     return 'default';
37 }
38
39 sub getlocale {
40     return shift->{accepted_locale};
41 }
42
43 sub _fetchpl {
44     my $accepted = shift;
45     my $f = $LocaleFile{$accepted};
46     return if !$f;
47     $f .= $PL_EXT;
48     my $path = File::Spec->catfile($ModPath, $f);
49     my $h = do $path;
50     croak "Unicode/Collate/Locale/$f can't be found" if !$h;
51     return $h;
52 }
53
54 sub new {
55     my $class = shift;
56     my %hash = @_;
57     $hash{accepted_locale} = _locale($hash{locale});
58
59     if (exists $hash{table}) {
60         croak "your table can't be used with Unicode::Collate::Locale";
61     }
62     $hash{table} = $KeyPath;
63
64     my $href = _fetchpl($hash{accepted_locale});
65     while (my($k,$v) = each %$href) {
66         if (exists $hash{$k}) {
67             croak "$k is reserved by $hash{locale}, can't be overwritten";
68         }
69         $hash{$k} = $v;
70     }
71     return $class->SUPER::new(%hash);
72 }
73
74 1;
75 __END__
76
77 =head1 NAME
78
79 Unicode::Collate::Locale - Linguistic tailoring for DUCET via Unicode::Collate
80
81 =head1 SYNOPSIS
82
83   use Unicode::Collate::Locale;
84
85   $Collator = Unicode::Collate::Locale->
86       new(locale => $locale_name, %tailoring);
87
88   @sorted = $Collator->sort(@not_sorted);
89
90 =head1 DESCRIPTION
91
92 This module provides linguistic tailoring for it
93 taking advantage of C<Unicode::Collate>.
94
95 =head2 Constructor
96
97 The C<new> method returns a collator object.
98
99 A parameter list for the constructor is a hash, which can include
100 a special key C<'locale'> and its value (case-insensitive) standing
101 for a two-letter language code (ISO-639) like C<'en'> for English.
102 For example, C<Unicode::Collate::Locale-E<gt>new(locale =E<gt> 'FR')>
103 returns a collator tailored for French.
104
105 C<$locale_name> may be suffixed with a territory(country)
106 code or a variant code, which are separated with C<'_'>.
107 E.g. C<en_US> for English in USA,
108 C<es_ES_traditional> for Spanish in Spain (Traditional),
109
110 If C<$localename> is not defined,
111 fallback is selected in the following order:
112
113     1. language_territory_variant
114     2. language_territory
115     3. language__variant
116     4. language
117     5. default
118
119 Tailoring tags provided by C<Unicode::Collate> are allowed
120 as long as they are not used for C<'locale'> support.
121 Esp. the C<table> tag is always untailorable
122 since it is reserved for DUCET.
123
124 E.g. a collator for French, which ignores diacritics and case difference
125 (i.e. level 1), with reversed case ordering and no normalization.
126
127     Unicode::Collate::Locale->new(
128         level => 1,
129         locale => 'fr',
130         upper_before_lower => 1,
131         normalization => undef
132     )
133
134 =head2 Methods
135
136 C<Unicode::Collate::Locale> is a subclass of C<Unicode::Collate>
137 and methods other than C<new> are inherited from C<Unicode::Collate>.
138
139 Here is a list of additional methods:
140
141 =over 4
142
143 =item C<$Collator-E<gt>getlocale>
144
145 Returns a language code accepted and used actually on collation.
146 If linguistic tailoring is not provided for a language code you passed
147 (intensionally for some languages, or due to the incomplete implementation),
148 this method returns a string C<'default'> meaning no special tailoring.
149
150 =back
151
152 =head2 A list of tailorable locales
153
154       locale name       description
155     ----------------------------------------------------------
156       af                Afrikaans
157       az                Azerbaijani (Azeri)
158       ca                Catalan
159       cs                Czech
160       cy                Welsh
161       da                Danish
162       eo                Esperanto
163       es                Spanish
164       es__traditional   Spanish ('ch' and 'll' as a grapheme)
165       et                Estonian
166       fi                Finnish
167       fil               Filipino
168       fo                Faroese
169       fr                French
170       ha                Hausa
171       haw               Hawaiian
172       is                Icelandic
173       kl                Kalaallisut
174       lt                Lithuanian
175       lv                Latvian
176       mt                Maltese
177       nb                Norwegian Bokmal
178       nn                Norwegian Nynorsk
179       pl                Polish
180       ro                Romanian
181       sk                Slovak
182       sl                Slovenian
183       sv                Swedish
184       sw                Swahili
185       tr                Turkish
186       wo                Wolof
187       yo                Yoruba
188
189 =head1 INSTALL
190
191 Installation of Unicode::Collate::Locale requires F<Collate/Locale.pm>,
192 F<Collate/Locale/*.pm> and F<Collate/allkeys.txt>.  On building,
193 Unicode::Collate::Locale doesn't require F<data/*.txt> and F<mklocale>.
194 Tests for Unicode::Collate::Locale are named F<t/loc_*.t>.
195
196 =head1 AUTHOR
197
198 The Unicode::Collate::Locale module for perl was written
199 by SADAHIRO Tomoyuki, <SADAHIRO@cpan.org>.
200 This module is Copyright(C) 2004-2010, SADAHIRO Tomoyuki. Japan.
201 All rights reserved.
202
203 This module is free software; you can redistribute it and/or
204 modify it under the same terms as Perl itself.
205
206 =head1 SEE ALSO
207
208 =over 4
209
210 =item Unicode Collation Algorithm - UTS #10
211
212 L<http://www.unicode.org/reports/tr10/>
213
214 =item The Default Unicode Collation Element Table (DUCET)
215
216 L<http://www.unicode.org/Public/UCA/latest/allkeys.txt>
217
218 =item CLDR - Unicode Common Locale Data Repository
219
220 L<http://cldr.unicode.org/>
221
222 =item L<Unicode::Collate>
223
224 =item L<Unicode::Normalize>
225
226 =back
227
228 =cut