This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
POD nit found by Slaven Rezic.
[perl5.git] / ext / Hash / Util / lib / Hash / Util.pm
index a4f143e..0fa1469 100644 (file)
@@ -50,18 +50,6 @@ Hash::Util - A selection of general-utility hash subroutines
 
 =head1 SYNOPSIS
 
-  # Field hashes
-
-  use Hash::Util qw(fieldhash fieldhashes);
-
-  # Create a single field hash
-  fieldhash my %foo;
-
-  # Create three at once...
-  fieldhashes \ my(%foo, %bar, %baz);
-  # ...or any number
-  fieldhashes @hashrefs;
-
   # Restricted hashes
 
   use Hash::Util qw(
@@ -79,20 +67,20 @@ Hash::Util - A selection of general-utility hash subroutines
   lock_keys(%hash, @keyset);
   lock_keys_plus(%hash, @additional_keys);
 
-  #Ways to inspect the properties of a restricted hash
-  my @legal=legal_keys(%hash);
-  my @hidden=hidden_keys(%hash);
-  my $ref=all_keys(%hash,@keys,@hidden);
-  my $is_locked=hash_locked(%hash);
+  # Ways to inspect the properties of a restricted hash
+  my @legal = legal_keys(%hash);
+  my @hidden = hidden_keys(%hash);
+  my $ref = all_keys(%hash,@keys,@hidden);
+  my $is_locked = hash_locked(%hash);
 
-  #Remove restrictions on the hash
+  # Remove restrictions on the hash
   unlock_keys(%hash);
 
-  #Lock individual values in a hash
+  # Lock individual values in a hash
   lock_value  (%hash, 'foo');
   unlock_value(%hash, 'foo');
 
-  #Ways to change the restrictions on both keys and values
+  # Ways to change the restrictions on both keys and values
   lock_hash  (%hash);
   unlock_hash(%hash);
 
@@ -100,23 +88,16 @@ Hash::Util - A selection of general-utility hash subroutines
 
 =head1 DESCRIPTION
 
-C<Hash::Util> contains special functions for manipulating hashes that
-don't really warrant a keyword.
-
-By default C<Hash::Util> does not export anything.
+C<Hash::Util> and C<Hash::Util::FieldHash> contain special functions
+for manipulating hashes that don't really warrant a keyword.
 
-=head2 Field hashes
+C<Hash::Util> contains a set of functions that support
+L<restricted hashes|/"Restricted hashes">. These are described in
+this document.  C<Hash::Util::FieldHash> contains an (unrelated)
+set of functions that support the use of hashes in
+I<inside-out classes>, described in L<Hash::Util::FieldHash>.
 
-Field hashes are designed to maintain an association of a reference
-with a value. The association is independent of the bless status of
-the key, it is thread safe and garbage-collected.  These properties
-are desirable in the construction of inside-out classes.
-
-When used with keys that are plain scalars (not references), field
-hashes behave like normal hashes.
-
-Field hashes are defined in a separate module for which C<Hash::Util>
-is a front end.  For a detailed description see L<Hash::Util::FieldHash>.
+By default C<Hash::Util> does not export anything.
 
 =head2 Restricted hashes
 
@@ -270,7 +251,7 @@ sub unlock_value (\%$) { unlock_ref_value(@_) }
 
     lock_hash(%hash);
 
-lock_hash() locks an entire hash, making all keys and values readonly.
+lock_hash() locks an entire hash, making all keys and values read-only.
 No value can be changed, no keys can be added or deleted.
 
     unlock_hash(%hash);
@@ -317,7 +298,7 @@ sub unlock_hash (\%) { unlock_hashref(@_) }
     lock_hash_recurse(%hash);
 
 lock_hash() locks an entire hash and any hashes it references recursively,
-making all keys and values readonly. No value can be changed, no keys can
+making all keys and values read-only. No value can be changed, no keys can
 be added or deleted.
 
 B<Only> recurses into hashes that are referenced by another hash. Thus a
@@ -389,19 +370,19 @@ sub all_keys{}
 sub legal_keys(\%) { legal_ref_keys(@_)  }
 sub hidden_keys(\%){ hidden_ref_keys(@_) }
 
-=item b<legal_keys>
+=item B<legal_keys>
 
-  my @keys=legal_keys(%hash);
+  my @keys = legal_keys(%hash);
 
-Returns a list of the keys that are legal in a restricted hash.
+Returns the list of the keys that are legal in a restricted hash.
 In the case of an unrestricted hash this is identical to calling
 keys(%hash).
 
 =item B<hidden_keys>
 
-  my @keys=hidden_keys(%hash);
+  my @keys = hidden_keys(%hash);
 
-Returns a list of the keys that are legal in a restricted hash but
+Returns the list of the keys that are legal in a restricted hash but
 do not have a value associated to them. Thus if 'foo' is a
 "hidden" key of the %hash it will return false for both C<defined>
 and C<exists> tests.
@@ -410,7 +391,7 @@ In the case of an unrestricted hash this will return an empty list.
 
 B<NOTE> this is an experimental feature that is heavily dependent
 on the current implementation of restricted hashes. Should the
-implementation change this routine may become meaningless in which
+implementation change, this routine may become meaningless, in which
 case it will return an empty list.
 
 =item B<all_keys>
@@ -423,19 +404,19 @@ keys that have not been utilized.
 
 Returns a reference to the hash.
 
-In the case of an unrestricted hash this will be equivelent to
+In the case of an unrestricted hash this will be equivalent to
 
-  $ref=do{
-            @keys  =keys %hash;
-            @hidden=();
-            \%hash
-         };
+  $ref = do {
+      @keys = keys %hash;
+      @hidden = ();
+      \%hash
+  };
 
 B<NOTE> this is an experimental feature that is heavily dependent
 on the current implementation of restricted hashes. Should the
 implementation change this routine may become meaningless in which
 case it will behave identically to how it would behave on an
-unrestrcited hash.
+unrestricted hash.
 
 =item B<hash_seed>
 
@@ -459,9 +440,9 @@ sub hash_seed () {
 
 =item B<hv_store>
 
-  my $sv=0;
+  my $sv = 0;
   hv_store(%hash,$key,$sv) or die "Failed to alias!";
-  $hash{$key}=1;
+  $hash{$key} = 1;
   print $sv; # prints 1
 
 Stores an alias to a variable in a hash instead of copying the value.
@@ -470,7 +451,7 @@ Stores an alias to a variable in a hash instead of copying the value.
 
 =head2 Operating on references to hashes.
 
-Most subroutines documented in this module have equivelent versions
+Most subroutines documented in this module have equivalent versions
 that operate on references to hashes instead of native hashes.
 The following is a list of these subs. They are identical except
 in name and in that instead of taking a %hash they take a $hashref,
@@ -516,7 +497,7 @@ leaves the C<%hash> empty rather than with its original contents.
 =head1 BUGS
 
 The interface exposed by this module is very close to the current
-imlementation of restricted hashes. Over time it is expected that
+implementation of restricted hashes. Over time it is expected that
 this behavior will be extended and the interface abstracted further.
 
 =head1 AUTHOR
@@ -530,8 +511,9 @@ Additional code by Yves Orton.
 
 =head1 SEE ALSO
 
-L<Scalar::Util>, L<List::Util>, L<Hash::Util>,
-and L<perlsec/"Algorithmic Complexity Attacks">.
+L<Scalar::Util>, L<List::Util> and L<perlsec/"Algorithmic Complexity Attacks">.
+
+L<Hash::Util::FieldHash>.
 
 =cut