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