7 use warnings::register;
8 use Scalar::Util qw(reftype);
11 our @ISA = qw(Exporter);
17 lock_value unlock_value
19 lock_keys_plus hash_locked
20 hidden_keys legal_keys
22 lock_ref_keys unlock_ref_keys
23 lock_ref_value unlock_ref_value
24 lock_hashref unlock_hashref
25 lock_ref_keys_plus hashref_locked
26 hidden_ref_keys legal_ref_keys
33 local @ISA = qw(DynaLoader);
34 bootstrap Hash::Util $VERSION;
38 if ( grep /fieldhash/, @_ ) {
39 require Hash::Util::FieldHash;
40 Hash::Util::FieldHash->import(':all'); # for re-export
43 goto &Exporter::import;
49 Hash::Util - A selection of general-utility hash subroutines
58 lock_value unlock_value
60 lock_keys_plus hash_locked
61 hidden_keys legal_keys
64 %hash = (foo => 42, bar => 23);
65 # Ways to restrict a hash
67 lock_keys(%hash, @keyset);
68 lock_keys_plus(%hash, @additional_keys);
70 # Ways to inspect the properties of a restricted hash
71 my @legal = legal_keys(%hash);
72 my @hidden = hidden_keys(%hash);
73 my $ref = all_keys(%hash,@keys,@hidden);
74 my $is_locked = hash_locked(%hash);
76 # Remove restrictions on the hash
79 # Lock individual values in a hash
80 lock_value (%hash, 'foo');
81 unlock_value(%hash, 'foo');
83 # Ways to change the restrictions on both keys and values
87 my $hashes_are_randomised = hash_seed() != 0;
91 C<Hash::Util> and C<Hash::Util::FieldHash> contain special functions
92 for manipulating hashes that don't really warrant a keyword.
94 C<Hash::Util> contains a set of functions that support
95 L<restricted hashes|/"Restricted hashes">. These are described in
96 this document. C<Hash::Util::FieldHash> contains an (unrelated)
97 set of functions that support the use of hashes in
98 I<inside-out classes>, described in L<Hash::Util::FieldHash>.
100 By default C<Hash::Util> does not export anything.
102 =head2 Restricted hashes
104 5.8.0 introduces the ability to restrict a hash to a certain set of
105 keys. No keys outside of this set can be added. It also introduces
106 the ability to lock an individual key so it cannot be deleted and the
107 ability to ensure that an individual value cannot be changed.
109 This is intended to largely replace the deprecated pseudo-hashes.
118 lock_keys(%hash, @keys);
120 Restricts the given %hash's set of keys to @keys. If @keys is not
121 given it restricts it to its current keyset. No more keys can be
122 added. delete() and exists() will still work, but will not alter
123 the set of allowed keys. B<Note>: the current implementation prevents
124 the hash from being bless()ed while it is in a locked state. Any attempt
125 to do so will raise an exception. Of course you can still bless()
126 the hash before you call lock_keys() so this shouldn't be a problem.
130 Removes the restriction on the %hash's keyset.
132 B<Note> that if any of the values of the hash have been locked they will not be unlocked
133 after this sub executes.
135 Both routines return a reference to the hash operated on.
140 my($hash, @keys) = @_;
142 Internals::hv_clear_placeholders %$hash;
144 my %keys = map { ($_ => 1) } @keys;
145 my %original_keys = map { ($_ => 1) } keys %$hash;
146 foreach my $k (keys %original_keys) {
147 croak "Hash has key '$k' which is not in the new key set"
151 foreach my $k (@keys) {
152 $hash->{$k} = undef unless exists $hash->{$k};
154 Internals::SvREADONLY %$hash, 1;
156 foreach my $k (@keys) {
157 delete $hash->{$k} unless $original_keys{$k};
161 Internals::SvREADONLY %$hash, 1;
167 sub unlock_ref_keys {
170 Internals::SvREADONLY %$hash, 0;
174 sub lock_keys (\%;@) { lock_ref_keys(@_) }
175 sub unlock_keys (\%) { unlock_ref_keys(@_) }
177 =item B<lock_keys_plus>
179 lock_keys_plus(%hash,@additional_keys)
181 Similar to C<lock_keys()>, with the difference being that the optional key list
182 specifies keys that may or may not be already in the hash. Essentially this is
185 lock_keys(%hash,@additional_keys,keys %hash);
187 Returns a reference to %hash
192 sub lock_ref_keys_plus {
195 Internals::hv_clear_placeholders(%$hash);
196 foreach my $key (@keys) {
197 unless (exists($hash->{$key})) {
202 Internals::SvREADONLY(%$hash,1);
203 delete @{$hash}{@delete};
207 sub lock_keys_plus(\%;@) { lock_ref_keys_plus(@_) }
212 =item B<unlock_value>
214 lock_value (%hash, $key);
215 unlock_value(%hash, $key);
217 Locks and unlocks the value for an individual key of a hash. The value of a
218 locked key cannot be changed.
220 Unless %hash has already been locked the key/value could be deleted
221 regardless of this setting.
223 Returns a reference to the %hash.
228 my($hash, $key) = @_;
229 # I'm doubtful about this warning, as it seems not to be true.
230 # Marking a value in the hash as RO is useful, regardless
231 # of the status of the hash itself.
232 carp "Cannot usefully lock values in an unlocked hash"
233 if !Internals::SvREADONLY(%$hash) && warnings::enabled;
234 Internals::SvREADONLY $hash->{$key}, 1;
238 sub unlock_ref_value {
239 my($hash, $key) = @_;
240 Internals::SvREADONLY $hash->{$key}, 0;
244 sub lock_value (\%$) { lock_ref_value(@_) }
245 sub unlock_value (\%$) { unlock_ref_value(@_) }
254 lock_hash() locks an entire hash, making all keys and values read-only.
255 No value can be changed, no keys can be added or deleted.
259 unlock_hash() does the opposite of lock_hash(). All keys and values
260 are made writable. All values can be changed and keys can be added
263 Returns a reference to the %hash.
270 lock_ref_keys($hash);
272 foreach my $value (values %$hash) {
273 Internals::SvREADONLY($value,1);
282 foreach my $value (values %$hash) {
283 Internals::SvREADONLY($value, 0);
286 unlock_ref_keys($hash);
291 sub lock_hash (\%) { lock_hashref(@_) }
292 sub unlock_hash (\%) { unlock_hashref(@_) }
294 =item B<lock_hash_recurse>
296 =item B<unlock_hash_recurse>
298 lock_hash_recurse(%hash);
300 lock_hash() locks an entire hash and any hashes it references recursively,
301 making all keys and values read-only. No value can be changed, no keys can
304 B<Only> recurses into hashes that are referenced by another hash. Thus a
305 Hash of Hashes (HoH) will all be restricted, but a Hash of Arrays of Hashes
306 (HoAoH) will only have the top hash restricted.
308 unlock_hash_recurse(%hash);
310 unlock_hash_recurse() does the opposite of lock_hash_recurse(). All keys and
311 values are made writable. All values can be changed and keys can be added
312 and deleted. Identical recursion restrictions apply as to lock_hash_recurse().
314 Returns a reference to the %hash.
318 sub lock_hashref_recurse {
321 lock_ref_keys($hash);
322 foreach my $value (values %$hash) {
323 if (reftype($value) eq 'HASH') {
324 lock_hashref_recurse($value);
326 Internals::SvREADONLY($value,1);
331 sub unlock_hashref_recurse {
334 foreach my $value (values %$hash) {
335 if (reftype($value) eq 'HASH') {
336 unlock_hashref_recurse($value);
338 Internals::SvREADONLY($value,1);
340 unlock_ref_keys($hash);
344 sub lock_hash_recurse (\%) { lock_hashref_recurse(@_) }
345 sub unlock_hash_recurse (\%) { unlock_hashref_recurse(@_) }
348 =item B<hash_unlocked>
350 hash_unlocked(%hash) and print "Hash is unlocked!\n";
352 Returns true if the hash and its keys are unlocked.
356 sub hashref_unlocked {
358 return Internals::SvREADONLY($hash)
361 sub hash_unlocked(\%) { hashref_unlocked(@_) }
363 =for demerphqs_editor
365 sub hidden_ref_keys{}
370 sub legal_keys(\%) { legal_ref_keys(@_) }
371 sub hidden_keys(\%){ hidden_ref_keys(@_) }
375 my @keys = legal_keys(%hash);
377 Returns the list of the keys that are legal in a restricted hash.
378 In the case of an unrestricted hash this is identical to calling
383 my @keys = hidden_keys(%hash);
385 Returns the list of the keys that are legal in a restricted hash but
386 do not have a value associated to them. Thus if 'foo' is a
387 "hidden" key of the %hash it will return false for both C<defined>
390 In the case of an unrestricted hash this will return an empty list.
392 B<NOTE> this is an experimental feature that is heavily dependent
393 on the current implementation of restricted hashes. Should the
394 implementation change, this routine may become meaningless, in which
395 case it will return an empty list.
399 all_keys(%hash,@keys,@hidden);
401 Populates the arrays @keys with the all the keys that would pass
402 an C<exists> tests, and populates @hidden with the remaining legal
403 keys that have not been utilized.
405 Returns a reference to the hash.
407 In the case of an unrestricted hash this will be equivalent to
415 B<NOTE> this is an experimental feature that is heavily dependent
416 on the current implementation of restricted hashes. Should the
417 implementation change this routine may become meaningless in which
418 case it will behave identically to how it would behave on an
423 my $hash_seed = hash_seed();
425 hash_seed() returns the seed number used to randomise hash ordering.
426 Zero means the "traditional" random hash ordering, non-zero means the
427 new even more random hash ordering introduced in Perl 5.8.1.
429 B<Note that the hash seed is sensitive information>: by knowing it one
430 can craft a denial-of-service attack against Perl code, even remotely,
431 see L<perlsec/"Algorithmic Complexity Attacks"> for more information.
432 B<Do not disclose the hash seed> to people who don't need to know it.
433 See also L<perlrun/PERL_HASH_SEED_DEBUG>.
438 Internals::rehash_seed();
444 hv_store(%hash,$key,$sv) or die "Failed to alias!";
446 print $sv; # prints 1
448 Stores an alias to a variable in a hash instead of copying the value.
452 =head2 Operating on references to hashes.
454 Most subroutines documented in this module have equivalent versions
455 that operate on references to hashes instead of native hashes.
456 The following is a list of these subs. They are identical except
457 in name and in that instead of taking a %hash they take a $hashref,
458 and additionally are not prototyped.
464 =item unlock_ref_keys
466 =item lock_ref_keys_plus
470 =item unlock_ref_value
476 =item lock_hashref_recurse
478 =item unlock_hashref_recurse
480 =item hash_ref_unlocked
484 =item hidden_ref_keys
490 Note that the trapping of the restricted operations is not atomic:
493 eval { %hash = (illegal_key => 1) }
495 leaves the C<%hash> empty rather than with its original contents.
499 The interface exposed by this module is very close to the current
500 implementation of restricted hashes. Over time it is expected that
501 this behavior will be extended and the interface abstracted further.
505 Michael G Schwern <schwern@pobox.com> on top of code by Nick
506 Ing-Simmons and Jeffrey Friedl.
508 hv_store() is from Array::RefElem, Copyright 2000 Gisle Aas.
510 Additional code by Yves Orton.
514 L<Scalar::Util>, L<List::Util> and L<perlsec/"Algorithmic Complexity Attacks">.
516 L<Hash::Util::FieldHash>.