A swath of VERSION patches from Nicholas Clark.

[p5sagit/p5-mst-13.2.git] / lib / Hash / Util.pm

diff --git a/lib/Hash/Util.pm b/lib/Hash/Util.pm
index f6fed97..658fd86 100644 (file)
--- a/lib/Hash/Util.pm
+++ b/lib/Hash/Util.pm
@@ -9,8 +9,7 @@ our @ISA        = qw(Exporter);
 our @EXPORT_OK  = qw(lock_keys unlock_keys lock_value unlock_value
                      lock_hash unlock_hash
                     );
-our $VERSION    = 0.04;
-
+our $VERSION    = 0.05;
 
 =head1 NAME
 
@@ -18,10 +17,9 @@ Hash::Util - A selection of general-utility hash subroutines
 
 =head1 SYNOPSIS
 
-  use Hash::Util qw(lock_keys   unlock_keys 
+  use Hash::Util qw(lock_keys   unlock_keys
                     lock_value  unlock_value
-                    lock_hash   unlock_hash
-                   );
+                    lock_hash   unlock_hash);
 
   %hash = (foo => 42, bar => 23);
   lock_keys(%hash);
@@ -34,7 +32,6 @@ Hash::Util - A selection of general-utility hash subroutines
   lock_hash  (%hash);
   unlock_hash(%hash);
 
-
 =head1 DESCRIPTION
 
 C<Hash::Util> contains special functions for manipulating hashes that
@@ -60,12 +57,15 @@ This is intended to largely replace the deprecated pseudo-hashes.
   lock_keys(%hash);
   lock_keys(%hash, @keys);
 
-  unlock_keys(%hash;)
-
 Restricts the given %hash's set of keys to @keys.  If @keys is not
 given it restricts it to its current keyset.  No more keys can be
-added.  delete() and exists() will still work, but it does not effect
-the set of allowed keys.
+added. delete() and exists() will still work, but will not alter
+the set of allowed keys. B<Note>: the current implementation prevents
+the hash from being bless()ed while it is in a locked state. Any attempt
+to do so will raise an exception. Of course you can still bless()
+the hash before you call lock_keys() so this shouldn't be a problem.
+
+  unlock_keys(%hash);
 
 Removes the restriction on the %hash's keyset.
 
@@ -74,6 +74,7 @@ Removes the restriction on the %hash's keyset.
 sub lock_keys (\%;@) {
     my($hash, @keys) = @_;
 
+    Internals::hv_clear_placeholders %$hash;
     if( @keys ) {
         my %keys = map { ($_ => 1) } @keys;
         my %original_keys = map { ($_ => 1) } keys %$hash;
@@ -96,22 +97,22 @@ sub lock_keys (\%;@) {
         Internals::SvREADONLY %$hash, 1;
     }
 
-    return undef;
+    return;
 }
 
 sub unlock_keys (\%) {
     my($hash) = shift;
 
     Internals::SvREADONLY %$hash, 0;
-    return undef;
+    return;
 }
 
 =item lock_value
 
 =item unlock_value
 
-  lock_key  (%hash, $key);
-  unlock_key(%hash, $key);
+  lock_value  (%hash, $key);
+  unlock_value(%hash, $key);
 
 Locks and unlocks an individual key of a hash.  The value of a locked
 key cannot be changed.
@@ -138,14 +139,15 @@ sub unlock_value (\%$) {
 =item B<unlock_hash>
 
     lock_hash(%hash);
-    unlock_hash(%hash);
 
 lock_hash() locks an entire hash, making all keys and values readonly.
 No value can be changed, no keys can be added or deleted.
 
-unlock_hash() does the opposite.  All keys and values are made
-read/write.  All values can be changed and keys can be added and
-deleted.
+    unlock_hash(%hash);
+
+unlock_hash() does the opposite of lock_hash().  All keys and values
+are made read/write.  All values can be changed and keys can be added
+and deleted.
 
 =cut
 
@@ -176,6 +178,15 @@ sub unlock_hash (\%) {
 
 =back
 
+=head1 CAVEATS
+
+Note that the trapping of the restricted operations is not atomic:
+for example
+
+    eval { %hash = (illegal_key => 1) }
+
+leaves the C<%hash> empty rather than with its original contents.
+
 =head1 AUTHOR
 
 Michael G Schwern <schwern@pobox.com> on top of code by Nick