README
1NAME
2 Tie::RegexpHash - Use regular expressions as hash keys
3
4SYNOPSIS
5 use Tie::RegexpHash;
6
7 my %hash;
8
9 tie %hash, 'Tie::RegexpHash';
10
11 $hash{ qr/^5(\s+|-)?gal(\.|lons?)?/i } = '5-GAL';
12
13 $hash{'5 gal'}; # returns "5-GAL"
14 $hash{'5GAL'}; # returns "5-GAL"
15 $hash{'5 gallon'}; # also returns "5-GAL"
16
17 my $rehash = Tie::RegexpHash->new();
18
19 $rehash->add( qr/\d+(\.\d+)?/, "contains a number" );
20 $rehash->add( qr/s$/, "ends with an \`s\'" );
21
22 $rehash->match( "foo 123" ); # returns "contains a number"
23 $rehash->match( "examples" ); # returns "ends with an `s'"
24
25DESCRIPTION
26 This module allows one to use regular expressions for hash keys, so that
27 values can be associated with anything that matches the key.
28
29 Hashes can be operated on using the standard tied hash interface in
30 Perl, as described in the SYNOPSIS, or using an object-oriented
31 interface described below.
32
33 Methods
34 new
35 my $obj = Tie::RegexpHash->new()
36
37 Creates a new "RegexpHash" (Regular Expression Hash) object.
38
39 add
40 $obj->add( $key, $value );
41
42 Adds a new key/value pair to the hash. *$key* can be a Regexp or a
43 string (which is compiled into a Regexp).
44
45 If *$key* is already defined, the value will be changed. If $key
46 matches an existing key (but is not the same), a warning will be
47 shown if warnings are enabled.
48
49 match
50 $value = $obj->match( $quasikey );
51
52 Returns the value associated with *$quasikey*. (*$quasikey* can be a
53 string which matches an existing Regexp or an actual Regexp.)
54 Returns 'undef' if there is no match.
55
56 Regexps are matched in the order they are defined.
57
58 match_exists
59 if ($obj->match_exists( $quasikey )) ...
60
61 Returns a true value if there exists a matching key.
62
63 remove
64 $value = $obj->remove( $quasikey );
65
66 Deletes the key associated with *$quasikey*. If *$quasikey* matches
67 an existing key (but is not the same), a warning will be shown.
68
69 Returns the value associated with the key.
70
71 clear
72 $obj->clear();
73
74 Removes all key/value pairs.
75
76AUTHOR
77 Alastair McGowan-Douglas <altreus@cpan.org>
78
79 Acknowledgments
80 Robert Rothenberg <rrwo at cpan.org>, previous maintainer.
81
82 Russell Harrison <rch at cpan.org> for patches adding support for
83 serialization.
84
85 Simon Hanmer <sch at scubaplus.co.uk> & Bart Vetters <robartes at
86 nirya.eb> for pointing out a bug in the logic of the _find() routine in
87 v0.10
88
89BUGS
90 Please report bugs on the github issues tracker
91 <https://github.com/Altreus/Tie-RegexpHash/issues>. Request Tracker
92 tickets will probably go unseen.
93
94LICENSE
95 Copyright (c) 2014-2015 Alastair McGowan-Douglas.
96
97 Copyright (c) 2001-2002, 2005-2006 Robert Rothenberg. All rights
98 reserved.
99
100 Portions Copyright (c) 2006 Russell Harrison. All rights reserved.
101
102 This program is free software. You can redistribute it under the same
103 terms as Perl itself; specifically the Artistic Licence
104 <http://dev.perl.org/licenses/artistic.html> or GPL
105 <http://dev.perl.org/licenses/gpl1.html>.
106
107SEE ALSO
108 Tie::Hash::Regex is a module with a complementary function. Rather than
109 a hash with Regexps as keys that match against fetches, it has standard
110 keys that are matched by Regexps in fetches.
111
112 Regexp::Match::Any matches many Regexps against a variable.
113
114 Regexp::Match::List is similar, but supports callbacks and various
115 optimizations.
116
117