Update Unicode-Collate to CPAN version 0.86
[perl.git] / cpan / Unicode-Collate / README
1 Unicode/Collate version 0.86
2 ===============================
3
4 NAME
5
6   Unicode::Collate - Unicode Collation Algorithm
7
8 SYNOPSIS
9
10   use Unicode::Collate;
11
12   #construct
13   $Collator = Unicode::Collate->new(%tailoring);
14
15   #sort
16   @sorted = $Collator->sort(@not_sorted);
17
18   #compare
19   $result = $Collator->cmp($a, $b); # returns 1, 0, or -1.
20   $result = $Collator->eq($a, $b);  # returns true/false
21     (similarly ->ne, ->lt, ->le, ->gt, ->ge)
22
23 Note: Strings in @not_sorted, $a and $b are interpreted
24 according to Perl's Unicode support. See perlunicode,
25 perluniintro, perlunitut, perlunifaq, utf8.
26 Otherwise you can use "preprocess" or should decode them before.
27
28 INSTALL
29
30   Perl 5.6.1 or later is required.
31   Perl 5.8.1 or later is recommended.
32
33   Though this distribution contains a subset of an old DUCET, named
34   "keys.txt", this one is intended only for doing a test of this module
35   and practically useless for any other purpose.
36
37   Installation of Unicode::Collate::Locale requires Collate/Locale.pm,
38   Collate/Locale/*.pm, Collate/CJK/*.pm and Collate/allkeys.txt.
39   On building, Unicode::Collate::Locale doesn't require any of data/*.txt,
40   gendata/*, and mklocale.
41   Tests for Unicode::Collate::Locale are named t/loc_*.t.
42
43 Since 0.54, XSUB that requires a C compiler will be built by default.
44 To install this module type the following:
45
46    perl Makefile.PL
47    make
48    make test
49    make install
50
51 Even if a C compiler is not available, pure Perl (i.e. non-XS) edition
52 is available; type the following:
53
54    perl disableXS
55    perl Makefile.PL
56    make
57    make test
58    make install
59
60 If you decide to install XSUB edition after trying to build pure Perl,
61 type the following:
62
63    make clean
64    perl enableXS
65    perl Makefile.PL
66    make
67    make test
68    make install
69
70 DEPENDENCIES
71
72   The conformant collation requires Unicode::Normalize (v 0.10 or later)
73   although Unicode::Collate can be used without Unicode::Normalize.
74
75 ABOUT DUCET
76
77   Though this module can be used without any C<table> file,
78   to use this module easily, it is recommended to install a table file
79   in the UCA format, by copying it under the directory
80   <a place in @INC>/Unicode/Collate.
81
82   You can install such a table file by adding it to "Collate" directory
83   (where "keys.txt" is placed) in this distribution before executing
84   Makefile.PL.
85
86   The most preferable one is "The Default Unicode Collation Element Table"
87   (aka DUCET), available from the Unicode Consortium's website:
88
89    http://www.unicode.org/Public/UCA/
90
91    http://www.unicode.org/Public/UCA/latest/allkeys.txt (latest version)
92
93   If DUCET is not installed, it is recommended to copy the file
94   from http://www.unicode.org/Public/UCA/latest/allkeys.txt
95   to <a place in @INC>/Unicode/Collate/allkeys.txt manually.
96
97 HOW TO CHANGE DUCET (NOT WARRANTED)
98
99   0. rewriting UCA_Version and Base_Unicode_Version in Collate.pm
100      and t/version.t is preferred.
101   1. replace Collate/allkeys.txt with a new DUCET.
102   2. run mklocale to generate new Locale/*.pl and Korean.pm.
103   3. replace Collate/Locale/*.pl with the new Locale/*.pl,
104      and Collate/CJK/Korean.pm with the new Korean.pm.
105   4. make test.
106      IF FAIL, it may require more changes, not be easy.
107
108 AUTHOR, COPYRIGHT AND LICENSE
109
110 The Unicode::Collate module for perl was written by SADAHIRO Tomoyuki,
111 <SADAHIRO@cpan.org>. This module is Copyright(C) 2001-2011,
112 SADAHIRO Tomoyuki. Japan. All rights reserved.
113
114 This module is free software; you can redistribute it and/or
115 modify it under the same terms as Perl itself.
116
117 The file Unicode/Collate/allkeys.txt was copied verbatim
118 from http://www.unicode.org/Public/UCA/6.0.0/allkeys.txt
119 This file is Copyright (c) 1991-2010 Unicode, Inc. All rights reserved.
120 Distributed under the Terms of Use in http://www.unicode.org/copyright.html