1Hash::Util(3pm)        Perl Programmers Reference Guide        Hash::Util(3pm)
2
3
4

NAME

6       Hash::Util - A selection of general-utility hash subroutines
7

SYNOPSIS

9         # Restricted hashes
10
11         use Hash::Util qw(
12                            hash_seed all_keys
13                            lock_keys unlock_keys
14                            lock_value unlock_value
15                            lock_hash unlock_hash
16                            lock_keys_plus hash_locked
17                            hidden_keys legal_keys
18                          );
19
20         %hash = (foo => 42, bar => 23);
21         # Ways to restrict a hash
22         lock_keys(%hash);
23         lock_keys(%hash, @keyset);
24         lock_keys_plus(%hash, @additional_keys);
25
26         # Ways to inspect the properties of a restricted hash
27         my @legal = legal_keys(%hash);
28         my @hidden = hidden_keys(%hash);
29         my $ref = all_keys(%hash,@keys,@hidden);
30         my $is_locked = hash_locked(%hash);
31
32         # Remove restrictions on the hash
33         unlock_keys(%hash);
34
35         # Lock individual values in a hash
36         lock_value  (%hash, 'foo');
37         unlock_value(%hash, 'foo');
38
39         # Ways to change the restrictions on both keys and values
40         lock_hash  (%hash);
41         unlock_hash(%hash);
42
43         my $hashes_are_randomised = hash_seed() != 0;
44

DESCRIPTION

46       "Hash::Util" and "Hash::Util::FieldHash" contain special functions for
47       manipulating hashes that don't really warrant a keyword.
48
49       "Hash::Util" contains a set of functions that support restricted
50       hashes. These are described in this document.  "Hash::Util::FieldHash"
51       contains an (unrelated) set of functions that support the use of hashes
52       in inside-out classes, described in Hash::Util::FieldHash.
53
54       By default "Hash::Util" does not export anything.
55
56   Restricted hashes
57       5.8.0 introduces the ability to restrict a hash to a certain set of
58       keys.  No keys outside of this set can be added.  It also introduces
59       the ability to lock an individual key so it cannot be deleted and the
60       ability to ensure that an individual value cannot be changed.
61
62       This is intended to largely replace the deprecated pseudo-hashes.
63
64       lock_keys
65       unlock_keys
66             lock_keys(%hash);
67             lock_keys(%hash, @keys);
68
69           Restricts the given %hash's set of keys to @keys.  If @keys is not
70           given it restricts it to its current keyset.  No more keys can be
71           added. delete() and exists() will still work, but will not alter
72           the set of allowed keys. Note: the current implementation prevents
73           the hash from being bless()ed while it is in a locked state. Any
74           attempt to do so will raise an exception. Of course you can still
75           bless() the hash before you call lock_keys() so this shouldn't be a
76           problem.
77
78             unlock_keys(%hash);
79
80           Removes the restriction on the %hash's keyset.
81
82           Note that if any of the values of the hash have been locked they
83           will not be unlocked after this sub executes.
84
85           Both routines return a reference to the hash operated on.
86
87       lock_keys_plus
88             lock_keys_plus(%hash,@additional_keys)
89
90           Similar to "lock_keys()", with the difference being that the
91           optional key list specifies keys that may or may not be already in
92           the hash. Essentially this is an easier way to say
93
94             lock_keys(%hash,@additional_keys,keys %hash);
95
96           Returns a reference to %hash
97
98       lock_value
99       unlock_value
100             lock_value  (%hash, $key);
101             unlock_value(%hash, $key);
102
103           Locks and unlocks the value for an individual key of a hash.  The
104           value of a locked key cannot be changed.
105
106           Unless %hash has already been locked the key/value could be deleted
107           regardless of this setting.
108
109           Returns a reference to the %hash.
110
111       lock_hash
112       unlock_hash
113               lock_hash(%hash);
114
115           lock_hash() locks an entire hash, making all keys and values read-
116           only.  No value can be changed, no keys can be added or deleted.
117
118               unlock_hash(%hash);
119
120           unlock_hash() does the opposite of lock_hash().  All keys and
121           values are made writable.  All values can be changed and keys can
122           be added and deleted.
123
124           Returns a reference to the %hash.
125
126       lock_hash_recurse
127       unlock_hash_recurse
128               lock_hash_recurse(%hash);
129
130           lock_hash() locks an entire hash and any hashes it references
131           recursively, making all keys and values read-only. No value can be
132           changed, no keys can be added or deleted.
133
134           Only recurses into hashes that are referenced by another hash. Thus
135           a Hash of Hashes (HoH) will all be restricted, but a Hash of Arrays
136           of Hashes (HoAoH) will only have the top hash restricted.
137
138               unlock_hash_recurse(%hash);
139
140           unlock_hash_recurse() does the opposite of lock_hash_recurse().
141           All keys and values are made writable.  All values can be changed
142           and keys can be added and deleted. Identical recursion restrictions
143           apply as to lock_hash_recurse().
144
145           Returns a reference to the %hash.
146
147       hash_unlocked
148             hash_unlocked(%hash) and print "Hash is unlocked!\n";
149
150           Returns true if the hash and its keys are unlocked.
151
152       legal_keys
153             my @keys = legal_keys(%hash);
154
155           Returns the list of the keys that are legal in a restricted hash.
156           In the case of an unrestricted hash this is identical to calling
157           keys(%hash).
158
159       hidden_keys
160             my @keys = hidden_keys(%hash);
161
162           Returns the list of the keys that are legal in a restricted hash
163           but do not have a value associated to them. Thus if 'foo' is a
164           "hidden" key of the %hash it will return false for both "defined"
165           and "exists" tests.
166
167           In the case of an unrestricted hash this will return an empty list.
168
169           NOTE this is an experimental feature that is heavily dependent on
170           the current implementation of restricted hashes. Should the
171           implementation change, this routine may become meaningless, in
172           which case it will return an empty list.
173
174       all_keys
175             all_keys(%hash,@keys,@hidden);
176
177           Populates the arrays @keys with the all the keys that would pass an
178           "exists" tests, and populates @hidden with the remaining legal keys
179           that have not been utilized.
180
181           Returns a reference to the hash.
182
183           In the case of an unrestricted hash this will be equivalent to
184
185             $ref = do {
186                 @keys = keys %hash;
187                 @hidden = ();
188                 \%hash
189             };
190
191           NOTE this is an experimental feature that is heavily dependent on
192           the current implementation of restricted hashes. Should the
193           implementation change this routine may become meaningless in which
194           case it will behave identically to how it would behave on an
195           unrestricted hash.
196
197       hash_seed
198               my $hash_seed = hash_seed();
199
200           hash_seed() returns the seed number used to randomise hash
201           ordering.  Zero means the "traditional" random hash ordering, non-
202           zero means the new even more random hash ordering introduced in
203           Perl 5.8.1.
204
205           Note that the hash seed is sensitive information: by knowing it one
206           can craft a denial-of-service attack against Perl code, even
207           remotely, see "Algorithmic Complexity Attacks" in perlsec for more
208           information.  Do not disclose the hash seed to people who don't
209           need to know it.  See also "PERL_HASH_SEED_DEBUG" in perlrun.
210
211       hv_store
212             my $sv = 0;
213             hv_store(%hash,$key,$sv) or die "Failed to alias!";
214             $hash{$key} = 1;
215             print $sv; # prints 1
216
217           Stores an alias to a variable in a hash instead of copying the
218           value.
219
220   Operating on references to hashes.
221       Most subroutines documented in this module have equivalent versions
222       that operate on references to hashes instead of native hashes.  The
223       following is a list of these subs. They are identical except in name
224       and in that instead of taking a %hash they take a $hashref, and
225       additionally are not prototyped.
226
227       lock_ref_keys
228       unlock_ref_keys
229       lock_ref_keys_plus
230       lock_ref_value
231       unlock_ref_value
232       lock_hashref
233       unlock_hashref
234       lock_hashref_recurse
235       unlock_hashref_recurse
236       hash_ref_unlocked
237       legal_ref_keys
238       hidden_ref_keys
239

CAVEATS

241       Note that the trapping of the restricted operations is not atomic: for
242       example
243
244           eval { %hash = (illegal_key => 1) }
245
246       leaves the %hash empty rather than with its original contents.
247

BUGS

249       The interface exposed by this module is very close to the current
250       implementation of restricted hashes. Over time it is expected that this
251       behavior will be extended and the interface abstracted further.
252

AUTHOR

254       Michael G Schwern <schwern@pobox.com> on top of code by Nick Ing-
255       Simmons and Jeffrey Friedl.
256
257       hv_store() is from Array::RefElem, Copyright 2000 Gisle Aas.
258
259       Additional code by Yves Orton.
260

SEE ALSO

262       Scalar::Util, List::Util and "Algorithmic Complexity Attacks" in
263       perlsec.
264
265       Hash::Util::FieldHash.
266
267
268
269perl v5.12.4                      2011-06-07                   Hash::Util(3pm)
Impressum