README

   1 NAME
   2     Hash::Normalize - Automatically normalize Unicode hash keys.
   3
   4 VERSION
   5     Version 0.01
   6
   7 SYNOPSIS
   8         use Hash::Normalize qw<normalize>;
   9
  10         normalize my %hash, 'NFC';
  11
  12         $hash{café} = 'coffee'; # NFD, "cafe\x{301}"
  13
  14         print $hash{café};      # NFD, "cafe\x{301}"
  15         # 'coffee' is printed
  16
  17         print $hash{café};      # NFC, "caf\x{e9}"
  18         # 'coffee' is also printed
  19
  20 DESCRIPTION
  21     This module provides an utility routine that augments a given Perl hash
  22     table so that its keys are automatically normalized following one of the
  23     Unicode normalization schemes. All the following actions on this hash
  24     will be made regardless of how the key used for the action is
  25     normalized.
  26
  27     Since this module does not use the "tie" mechanism, normalized hashes
  28     are indistinguishable from regular hashes as far as Perl is concerned,
  29     but this module also provides "get_normalization" to identify them if
  30     necessary.
  31
  32 FUNCTIONS
  33   "normalize"
  34         normalize %hash;
  35         normalize %hash, $mode;
  36
  37     Applies the Unicode normalization scheme $mode onto %hash. $mode
  38     defaults to 'NFC' if omitted, and should match
  39     "/^(?:(?:nf)?k?|fc)[cd]$/i" otherwise.
  40
  41     "normalize" will first try to forcefully normalize the existing keys in
  42     %hash to the new mode, but it will throw an exception if there are
  43     distinct keys that have the same normalization. All the keys
  44     subsequently used for fetches, stores, exists, deletes and list
  45     assignments are then first passed through the according normalization
  46     procedure. "keys %hash" will also return the list of normalized keys.
  47
  48   "get_normalization"
  49         my $mode = get_normalization %hash;
  50         normalize %hash, $mode;
  51
  52     Returns the current Unicode normalization scheme in use for %hash, or
  53     "undef" if it is a plain hash.
  54
  55 NORMALIZED SYMBOL LOOKUPS
  56     Stashes (Perl symbol tables) are implemented as plain hashes, therefore
  57     one can use "normalize %Pkg::" on them to make sure that Unicode symbol
  58     lookups are made regardless of normalization.
  59
  60         package Foo;
  61
  62         BEGIN {
  63          require Hash::Normalize;
  64          # Enforce NFC normalization
  65          Hash::Normalize::normalize(%Foo::, 'NFC')
  66         }
  67
  68         sub café { # NFD, "cafe\x{301}"
  69          return 'coffee'
  70         }
  71
  72         sub coffee_nfc {
  73          café() # NFC, "cafe\x{e9}"
  74         }
  75
  76         sub coffee_nfd {
  77          café() # NFD, "cafe\x{301}"
  78         }
  79
  80         # Both coffee_nfc() and coffee_nfd() return 'coffee'
  81
  82 CAVEATS
  83     Using a normalized hash is slightly slower than a plain hash, due to the
  84     normalization procedure and the overhead of magic.
  85
  86     If a hash is initialized from a normalized hash by list assignment
  87     ("%new = %normalized"), then the normalization scheme will not be
  88     carried over to the new hash, although its keys will initially be
  89     normalized like the ones from the original hash.
  90
  91 EXPORT
  92     The functions "normalize" and "get_normalization" are only exported on
  93     request by specifying their names in the module import list.
  94
  95 DEPENDENCIES
  96     perl 5.10.
  97
  98     Carp, Exporter (core since perl 5).
  99
 100     Unicode::Normalize (core since perl 5.8).
 101
 102     Variable::Magic 0.51.
 103
 104 AUTHOR
 105     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 106
 107     You can contact me by mail or on "irc.perl.org" (vincent).
 108
 109 BUGS
 110     Please report any bugs or feature requests to "bug-hash-normalize at
 111     rt.cpan.org", or through the web interface at
 112     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hash-Normalize>. I will
 113     be notified, and then you'll automatically be notified of progress on
 114     your bug as I make changes.
 115
 116 SUPPORT
 117     You can find documentation for this module with the perldoc command.
 118
 119         perldoc Hash::Normalize
 120
 121 COPYRIGHT & LICENSE
 122     Copyright 2017 Vincent Pit, all rights reserved.
 123
 124     This program is free software; you can redistribute it and/or modify it
 125     under the same terms as Perl itself.
 126