8 our @ISA = qw(Exporter);
9 our @EXPORT_OK = qw(lock_keys unlock_keys lock_value unlock_value
16 Hash::Util - A selection of general-utility hash subroutines
20 use Hash::Util qw(lock_keys unlock_keys
21 lock_value unlock_value
22 lock_hash unlock_hash);
24 %hash = (foo => 42, bar => 23);
26 lock_keys(%hash, @keyset);
29 lock_value (%hash, 'foo');
30 unlock_value(%hash, 'foo');
37 C<Hash::Util> contains special functions for manipulating hashes that
38 don't really warrant a keyword.
40 By default C<Hash::Util> does not export anything.
42 =head2 Restricted hashes
44 5.8.0 introduces the ability to restrict a hash to a certain set of
45 keys. No keys outside of this set can be added. It also introduces
46 the ability to lock an individual key so it cannot be deleted and the
47 value cannot be changed.
49 This is intended to largely replace the deprecated pseudo-hashes.
58 lock_keys(%hash, @keys);
60 Restricts the given %hash's set of keys to @keys. If @keys is not
61 given it restricts it to its current keyset. No more keys can be
62 added. delete() and exists() will still work, but will not alter
63 the set of allowed keys. B<Note>: the current implementation prevents
64 the hash from being bless()ed while it is in a locked state. Any attempt
65 to do so will raise an exception. Of course you can still bless()
66 the hash before you call lock_keys() so this shouldn't be a problem.
70 Removes the restriction on the %hash's keyset.
74 sub lock_keys (\%;@) {
75 my($hash, @keys) = @_;
77 Internals::hv_clear_placeholders %$hash;
79 my %keys = map { ($_ => 1) } @keys;
80 my %original_keys = map { ($_ => 1) } keys %$hash;
81 foreach my $k (keys %original_keys) {
82 die sprintf "Hash has key '$k' which is not in the new key ".
83 "set at %s line %d\n", (caller)[1,2]
87 foreach my $k (@keys) {
88 $hash->{$k} = undef unless exists $hash->{$k};
90 Internals::SvREADONLY %$hash, 1;
92 foreach my $k (@keys) {
93 delete $hash->{$k} unless $original_keys{$k};
97 Internals::SvREADONLY %$hash, 1;
103 sub unlock_keys (\%) {
106 Internals::SvREADONLY %$hash, 0;
114 lock_value (%hash, $key);
115 unlock_value(%hash, $key);
117 Locks and unlocks an individual key of a hash. The value of a locked
118 key cannot be changed.
120 %hash must have already been locked for this to have useful effect.
124 sub lock_value (\%$) {
125 my($hash, $key) = @_;
126 carp "Cannot usefully lock values in an unlocked hash"
127 unless Internals::SvREADONLY %$hash;
128 Internals::SvREADONLY $hash->{$key}, 1;
131 sub unlock_value (\%$) {
132 my($hash, $key) = @_;
133 Internals::SvREADONLY $hash->{$key}, 0;
143 lock_hash() locks an entire hash, making all keys and values readonly.
144 No value can be changed, no keys can be added or deleted.
148 unlock_hash() does the opposite of lock_hash(). All keys and values
149 are made read/write. All values can be changed and keys can be added
159 foreach my $key (keys %$hash) {
160 lock_value(%$hash, $key);
166 sub unlock_hash (\%) {
169 foreach my $key (keys %$hash) {
170 unlock_value(%$hash, $key);
183 Note that the trapping of the restricted operations is not atomic:
186 eval { %hash = (illegal_key => 1) }
188 leaves the C<%hash> empty rather than with its original contents.
192 Michael G Schwern <schwern@pobox.com> on top of code by Nick
193 Ing-Simmons and Jeffrey Friedl.
197 L<Scalar::Util>, L<List::Util>, L<Hash::Util>