home *** CD-ROM | disk | FTP | other *** search
/ PC World 2005 December (Special) / PCWorld_2005-12_Special_cd.bin / Bezpecnost / lsti / lsti.exe / framework-2.5.exe / Normalize.pm < prev    next >
Text File  |  2005-01-27  |  11KB  |  416 lines
  1. package Unicode::Normalize;
  2.  
  3. BEGIN {
  4.     unless ("A" eq pack('U', 0x41)) {
  5.     die "Unicode::Normalize cannot stringify a Unicode code point\n";
  6.     }
  7. }
  8.  
  9. use 5.006;
  10. use strict;
  11. use warnings;
  12. use Carp;
  13.  
  14. no warnings 'utf8';
  15.  
  16. our $VERSION = '0.30';
  17. our $PACKAGE = __PACKAGE__;
  18.  
  19. require Exporter;
  20. require DynaLoader;
  21.  
  22. our @ISA = qw(Exporter DynaLoader);
  23. our @EXPORT = qw( NFC NFD NFKC NFKD );
  24. our @EXPORT_OK = qw(
  25.     normalize decompose reorder compose
  26.     checkNFD checkNFKD checkNFC checkNFKC check
  27.     getCanon getCompat getComposite getCombinClass
  28.     isExclusion isSingleton isNonStDecomp isComp2nd isComp_Ex
  29.     isNFD_NO isNFC_NO isNFC_MAYBE isNFKD_NO isNFKC_NO isNFKC_MAYBE
  30.     FCD checkFCD FCC checkFCC composeContiguous
  31.     splitOnLastStarter
  32. );
  33. our %EXPORT_TAGS = (
  34.     all       => [ @EXPORT, @EXPORT_OK ],
  35.     normalize => [ @EXPORT, qw/normalize decompose reorder compose/ ],
  36.     check     => [ qw/checkNFD checkNFKD checkNFC checkNFKC check/ ],
  37.     fast      => [ qw/FCD checkFCD FCC checkFCC composeContiguous/ ],
  38. );
  39.  
  40. ######
  41.  
  42. bootstrap Unicode::Normalize $VERSION;
  43.  
  44. ######
  45.  
  46. sub pack_U {
  47.     return pack('U*', @_);
  48. }
  49.  
  50. sub unpack_U {
  51.     return unpack('U*', pack('U*').shift);
  52. }
  53.  
  54.  
  55. ##
  56. ## normalization forms
  57. ##
  58.  
  59. use constant COMPAT => 1;
  60.  
  61. sub NFD  ($) { reorder(decompose($_[0])) }
  62. sub NFKD ($) { reorder(decompose($_[0], COMPAT)) }
  63. sub NFC  ($) { compose(reorder(decompose($_[0]))) }
  64. sub NFKC ($) { compose(reorder(decompose($_[0], COMPAT))) }
  65.  
  66. sub FCD ($) {
  67.     my $str = shift;
  68.     return checkFCD($str) ? $str : NFD($str);
  69. }
  70. sub FCC ($) { composeContiguous(reorder(decompose($_[0]))) }
  71.  
  72. our %formNorm = (
  73.     NFC  => \&NFC,    C  => \&NFC,
  74.     NFD  => \&NFD,    D  => \&NFD,
  75.     NFKC => \&NFKC,    KC => \&NFKC,
  76.     NFKD => \&NFKD,    KD => \&NFKD,
  77.     FCD  => \&FCD,    FCC => \&FCC,
  78. );
  79.  
  80. sub normalize($$)
  81. {
  82.     my $form = shift;
  83.     my $str = shift;
  84.     return exists $formNorm{$form} 
  85.     ? $formNorm{$form}->($str)
  86.     : croak $PACKAGE."::normalize: invalid form name: $form";
  87. }
  88.  
  89.  
  90. ##
  91. ## quick check
  92. ##
  93.  
  94. our %formCheck = (
  95.     NFC  => \&checkNFC,     C  => \&checkNFC,
  96.     NFD  => \&checkNFD,     D  => \&checkNFD,
  97.     NFKC => \&checkNFKC,    KC => \&checkNFKC,
  98.     NFKD => \&checkNFKD,    KD => \&checkNFKD,
  99.     FCD  => \&checkFCD,     FCC => \&checkFCC,
  100. );
  101.  
  102. sub check($$)
  103. {
  104.     my $form = shift;
  105.     my $str = shift;
  106.     return exists $formCheck{$form} 
  107.     ? $formCheck{$form}->($str)
  108.     : croak $PACKAGE."::check: invalid form name: $form";
  109. }
  110.  
  111. 1;
  112. __END__
  113.  
  114. =head1 NAME
  115.  
  116. Unicode::Normalize - Unicode Normalization Forms
  117.  
  118. =head1 SYNOPSIS
  119.  
  120. (1) using function names exported by default:
  121.  
  122.   use Unicode::Normalize;
  123.  
  124.   $NFD_string  = NFD($string);  # Normalization Form D
  125.   $NFC_string  = NFC($string);  # Normalization Form C
  126.   $NFKD_string = NFKD($string); # Normalization Form KD
  127.   $NFKC_string = NFKC($string); # Normalization Form KC
  128.  
  129. (2) using function names exported on request:
  130.  
  131.   use Unicode::Normalize 'normalize';
  132.  
  133.   $NFD_string  = normalize('D',  $string);  # Normalization Form D
  134.   $NFC_string  = normalize('C',  $string);  # Normalization Form C
  135.   $NFKD_string = normalize('KD', $string);  # Normalization Form KD
  136.   $NFKC_string = normalize('KC', $string);  # Normalization Form KC
  137.  
  138. =head1 DESCRIPTION
  139.  
  140. Parameters:
  141.  
  142. C<$string> is used as a string under character semantics
  143. (see F<perlunicode>).
  144.  
  145. C<$codepoint> should be an unsigned integer
  146. representing a Unicode code point.
  147.  
  148. Note: Between XS edition and pure Perl edition,
  149. interpretation of C<$codepoint> as a decimal number has incompatibility.
  150. XS converts C<$codepoint> to an unsigned integer, but pure Perl does not.
  151. Do not use a floating point nor a negative sign in C<$codepoint>.
  152.  
  153. =head2 Normalization Forms
  154.  
  155. =over 4
  156.  
  157. =item C<$NFD_string = NFD($string)>
  158.  
  159. returns the Normalization Form D (formed by canonical decomposition).
  160.  
  161. =item C<$NFC_string = NFC($string)>
  162.  
  163. returns the Normalization Form C (formed by canonical decomposition
  164. followed by canonical composition).
  165.  
  166. =item C<$NFKD_string = NFKD($string)>
  167.  
  168. returns the Normalization Form KD (formed by compatibility decomposition).
  169.  
  170. =item C<$NFKC_string = NFKC($string)>
  171.  
  172. returns the Normalization Form KC (formed by compatibility decomposition
  173. followed by B<canonical> composition).
  174.  
  175. =item C<$FCD_string = FCD($string)>
  176.  
  177. If the given string is in FCD ("Fast C or D" form; cf. UTN #5),
  178. returns it without modification; otherwise returns an FCD string.
  179.  
  180. Note: FCD is not always unique, then plural forms may be equivalent
  181. each other. C<FCD()> will return one of these equivalent forms.
  182.  
  183. =item C<$FCC_string = FCC($string)>
  184.  
  185. returns the FCC form ("Fast C Contiguous"; cf. UTN #5).
  186.  
  187. Note: FCC is unique, as well as four normalization forms (NF*).
  188.  
  189. =item C<$normalized_string = normalize($form_name, $string)>
  190.  
  191. As C<$form_name>, one of the following names must be given.
  192.  
  193.   'C'  or 'NFC'  for Normalization Form C  (UAX #15)
  194.   'D'  or 'NFD'  for Normalization Form D  (UAX #15)
  195.   'KC' or 'NFKC' for Normalization Form KC (UAX #15)
  196.   'KD' or 'NFKD' for Normalization Form KD (UAX #15)
  197.  
  198.   'FCD'          for "Fast C or D" Form  (UTN #5)
  199.   'FCC'          for "Fast C Contiguous" (UTN #5)
  200.  
  201. =back
  202.  
  203. =head2 Decomposition and Composition
  204.  
  205. =over 4
  206.  
  207. =item C<$decomposed_string = decompose($string)>
  208.  
  209. =item C<$decomposed_string = decompose($string, $useCompatMapping)>
  210.  
  211. Decomposes the specified string and returns the result.
  212.  
  213. If the second parameter (a boolean) is omitted or false, decomposes it
  214. using the Canonical Decomposition Mapping.
  215. If true, decomposes it using the Compatibility Decomposition Mapping.
  216.  
  217. The string returned is not always in NFD/NFKD.
  218. Reordering may be required.
  219.  
  220.     $NFD_string  = reorder(decompose($string));       # eq. to NFD()
  221.     $NFKD_string = reorder(decompose($string, TRUE)); # eq. to NFKD()
  222.  
  223. =item C<$reordered_string  = reorder($string)>
  224.  
  225. Reorders the combining characters and the like in the canonical ordering
  226. and returns the result.
  227.  
  228. E.g., when you have a list of NFD/NFKD strings,
  229. you can get the concatenated NFD/NFKD string from them, saying
  230.  
  231.     $concat_NFD  = reorder(join '', @NFD_strings);
  232.     $concat_NFKD = reorder(join '', @NFKD_strings);
  233.  
  234. =item C<$composed_string   = compose($string)>
  235.  
  236. Returns the string where composable pairs are composed.
  237.  
  238. E.g., when you have a NFD/NFKD string,
  239. you can get its NFC/NFKC string, saying
  240.  
  241.     $NFC_string  = compose($NFD_string);
  242.     $NFKC_string = compose($NFKD_string);
  243.  
  244. =back
  245.  
  246. =head2 Quick Check
  247.  
  248. (see Annex 8, UAX #15; and F<DerivedNormalizationProps.txt>)
  249.  
  250. The following functions check whether the string is in that normalization form.
  251.  
  252. The result returned will be:
  253.  
  254.     YES     The string is in that normalization form.
  255.     NO      The string is not in that normalization form.
  256.     MAYBE   Dubious. Maybe yes, maybe no.
  257.  
  258. =over 4
  259.  
  260. =item C<$result = checkNFD($string)>
  261.  
  262. returns C<YES> (C<1>) or C<NO> (C<empty string>).
  263.  
  264. =item C<$result = checkNFC($string)>
  265.  
  266. returns C<YES> (C<1>), C<NO> (C<empty string>), or C<MAYBE> (C<undef>).
  267.  
  268. =item C<$result = checkNFKD($string)>
  269.  
  270. returns C<YES> (C<1>) or C<NO> (C<empty string>).
  271.  
  272. =item C<$result = checkNFKC($string)>
  273.  
  274. returns C<YES> (C<1>), C<NO> (C<empty string>), or C<MAYBE> (C<undef>).
  275.  
  276. =item C<$result = checkFCD($string)>
  277.  
  278. returns C<YES> (C<1>) or C<NO> (C<empty string>).
  279.  
  280. =item C<$result = checkFCC($string)>
  281.  
  282. returns C<YES> (C<1>), C<NO> (C<empty string>), or C<MAYBE> (C<undef>).
  283.  
  284. If a string is not in FCD, it must not be in FCC.
  285. So C<checkFCC($not_FCD_string)> should return C<NO>.
  286.  
  287. =item C<$result = check($form_name, $string)>
  288.  
  289. returns C<YES> (C<1>), C<NO> (C<empty string>), or C<MAYBE> (C<undef>).
  290.  
  291. C<$form_name> is alike to that for C<normalize()>.
  292.  
  293. =back
  294.  
  295. B<Note>
  296.  
  297. In the cases of NFD, NFKD, and FCD, the answer must be
  298. either C<YES> or C<NO>. The answer C<MAYBE> may be returned
  299. in the cases of NFC, NFKC, and FCC.
  300.  
  301. A C<MAYBE> string should contain at least one combining character
  302. or the like. For example, C<COMBINING ACUTE ACCENT> has
  303. the MAYBE_NFC/MAYBE_NFKC property.
  304.  
  305. Both C<checkNFC("A\N{COMBINING ACUTE ACCENT}")>
  306. and C<checkNFC("B\N{COMBINING ACUTE ACCENT}")> will return C<MAYBE>.
  307. C<"A\N{COMBINING ACUTE ACCENT}"> is not in NFC
  308. (its NFC is C<"\N{LATIN CAPITAL LETTER A WITH ACUTE}">),
  309. while C<"B\N{COMBINING ACUTE ACCENT}"> is in NFC.
  310.  
  311. If you want to check exactly, compare the string with its NFC/NFKC/FCC;
  312. i.e.,
  313.  
  314.     $string eq NFC($string)    # thorough than checkNFC($string)
  315.     $string eq NFKC($string)   # thorough than checkNFKC($string)
  316.     $string eq FCC($string)    # thorough than checkFCC($string)
  317.  
  318. =head2 Character Data
  319.  
  320. These functions are interface of character data used internally.
  321. If you want only to get Unicode normalization forms, you don't need
  322. call them yourself.
  323.  
  324. =over 4
  325.  
  326. =item C<$canonical_decomposed = getCanon($codepoint)>
  327.  
  328. If the character of the specified codepoint is canonically
  329. decomposable (including Hangul Syllables),
  330. returns the B<completely decomposed> string canonically equivalent to it.
  331.  
  332. If it is not decomposable, returns C<undef>.
  333.  
  334. =item C<$compatibility_decomposed = getCompat($codepoint)>
  335.  
  336. If the character of the specified codepoint is compatibility
  337. decomposable (including Hangul Syllables),
  338. returns the B<completely decomposed> string compatibility equivalent to it.
  339.  
  340. If it is not decomposable, returns C<undef>.
  341.  
  342. =item C<$codepoint_composite = getComposite($codepoint_here, $codepoint_next)>
  343.  
  344. If two characters here and next (as codepoints) are composable
  345. (including Hangul Jamo/Syllables and Composition Exclusions),
  346. returns the codepoint of the composite.
  347.  
  348. If they are not composable, returns C<undef>.
  349.  
  350. =item C<$combining_class = getCombinClass($codepoint)>
  351.  
  352. Returns the combining class of the character as an integer.
  353.  
  354. =item C<$is_exclusion = isExclusion($codepoint)>
  355.  
  356. Returns a boolean whether the character of the specified codepoint
  357. is a composition exclusion.
  358.  
  359. =item C<$is_singleton = isSingleton($codepoint)>
  360.  
  361. Returns a boolean whether the character of the specified codepoint is
  362. a singleton.
  363.  
  364. =item C<$is_non_starter_decomposition = isNonStDecomp($codepoint)>
  365.  
  366. Returns a boolean whether the canonical decomposition
  367. of the character of the specified codepoint
  368. is a Non-Starter Decomposition.
  369.  
  370. =item C<$may_be_composed_with_prev_char = isComp2nd($codepoint)>
  371.  
  372. Returns a boolean whether the character of the specified codepoint
  373. may be composed with the previous one in a certain composition
  374. (including Hangul Compositions, but excluding
  375. Composition Exclusions and Non-Starter Decompositions).
  376.  
  377. =back
  378.  
  379. =head2 EXPORT
  380.  
  381. C<NFC>, C<NFD>, C<NFKC>, C<NFKD>: by default.
  382.  
  383. C<normalize> and other some functions: on request.
  384.  
  385. =head1 AUTHOR
  386.  
  387. SADAHIRO Tomoyuki <SADAHIRO@cpan.org>
  388.  
  389.   http://homepage1.nifty.com/nomenclator/perl/
  390.  
  391.   Copyright(C) 2001-2004, SADAHIRO Tomoyuki. Japan. All rights reserved.
  392.  
  393.   This module is free software; you can redistribute it
  394.   and/or modify it under the same terms as Perl itself.
  395.  
  396. =head1 SEE ALSO
  397.  
  398. =over 4
  399.  
  400. =item http://www.unicode.org/reports/tr15/
  401.  
  402. Unicode Normalization Forms - UAX #15
  403.  
  404. =item http://www.unicode.org/Public/UNIDATA/DerivedNormalizationProps.txt
  405.  
  406. Derived Normalization Properties
  407.  
  408. =item http://www.unicode.org/notes/tn5/
  409.  
  410. Canonical Equivalence in Applications - UTN #5
  411.  
  412. =back
  413.  
  414. =cut
  415.  
  416.