home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl560.zip / lib / Tie / Hash.pm < prev    next >
Text File  |  2000-03-12  |  4KB  |  162 lines
  1. package Tie::Hash;
  2.  
  3. =head1 NAME
  4.  
  5. Tie::Hash, Tie::StdHash - base class definitions for tied hashes
  6.  
  7. =head1 SYNOPSIS
  8.  
  9.     package NewHash;
  10.     require Tie::Hash;
  11.     
  12.     @ISA = (Tie::Hash);
  13.     
  14.     sub DELETE { ... }        # Provides needed method
  15.     sub CLEAR { ... }        # Overrides inherited method
  16.     
  17.     
  18.     package NewStdHash;
  19.     require Tie::Hash;
  20.     
  21.     @ISA = (Tie::StdHash);
  22.     
  23.     # All methods provided by default, define only those needing overrides
  24.     sub DELETE { ... }
  25.     
  26.     
  27.     package main;
  28.     
  29.     tie %new_hash, 'NewHash';
  30.     tie %new_std_hash, 'NewStdHash';
  31.  
  32. =head1 DESCRIPTION
  33.  
  34. This module provides some skeletal methods for hash-tying classes. See
  35. L<perltie> for a list of the functions required in order to tie a hash
  36. to a package. The basic B<Tie::Hash> package provides a C<new> method, as well
  37. as methods C<TIEHASH>, C<EXISTS> and C<CLEAR>. The B<Tie::StdHash> package
  38. provides most methods required for hashes in L<perltie>. It inherits from
  39. B<Tie::Hash>, and causes tied hashes to behave exactly like standard hashes,
  40. allowing for selective overloading of methods. The C<new> method is provided
  41. as grandfathering in the case a class forgets to include a C<TIEHASH> method.
  42.  
  43. For developers wishing to write their own tied hashes, the required methods
  44. are briefly defined below. See the L<perltie> section for more detailed
  45. descriptive, as well as example code:
  46.  
  47. =over
  48.  
  49. =item TIEHASH classname, LIST
  50.  
  51. The method invoked by the command C<tie %hash, classname>. Associates a new
  52. hash instance with the specified class. C<LIST> would represent additional
  53. arguments (along the lines of L<AnyDBM_File> and compatriots) needed to
  54. complete the association.
  55.  
  56. =item STORE this, key, value
  57.  
  58. Store datum I<value> into I<key> for the tied hash I<this>.
  59.  
  60. =item FETCH this, key
  61.  
  62. Retrieve the datum in I<key> for the tied hash I<this>.
  63.  
  64. =item FIRSTKEY this
  65.  
  66. Return the (key, value) pair for the first key in the hash.
  67.  
  68. =item NEXTKEY this, lastkey
  69.  
  70. Return the next key for the hash.
  71.  
  72. =item EXISTS this, key
  73.  
  74. Verify that I<key> exists with the tied hash I<this>.
  75.  
  76. The B<Tie::Hash> implementation is a stub that simply croaks.
  77.  
  78. =item DELETE this, key
  79.  
  80. Delete the key I<key> from the tied hash I<this>.
  81.  
  82. =item CLEAR this
  83.  
  84. Clear all values from the tied hash I<this>.
  85.  
  86. =back
  87.  
  88. =head1 CAVEATS
  89.  
  90. The L<perltie> documentation includes a method called C<DESTROY> as
  91. a necessary method for tied hashes. Neither B<Tie::Hash> nor B<Tie::StdHash>
  92. define a default for this method. This is a standard for class packages,
  93. but may be omitted in favor of a simple default.
  94.  
  95. =head1 MORE INFORMATION
  96.  
  97. The packages relating to various DBM-related implementations (F<DB_File>,
  98. F<NDBM_File>, etc.) show examples of general tied hashes, as does the
  99. L<Config> module. While these do not utilize B<Tie::Hash>, they serve as
  100. good working examples.
  101.  
  102. =cut
  103.  
  104. use Carp;
  105. use warnings::register;
  106.  
  107. sub new {
  108.     my $pkg = shift;
  109.     $pkg->TIEHASH(@_);
  110. }
  111.  
  112. # Grandfather "new"
  113.  
  114. sub TIEHASH {
  115.     my $pkg = shift;
  116.     if (defined &{"${pkg}::new"}) {
  117.     warnings::warn "WARNING: calling ${pkg}->new since ${pkg}->TIEHASH is missing"
  118.         if warnings::enabled();
  119.     $pkg->new(@_);
  120.     }
  121.     else {
  122.     croak "$pkg doesn't define a TIEHASH method";
  123.     }
  124. }
  125.  
  126. sub EXISTS {
  127.     my $pkg = ref $_[0];
  128.     croak "$pkg doesn't define an EXISTS method";
  129. }
  130.  
  131. sub CLEAR {
  132.     my $self = shift;
  133.     my $key = $self->FIRSTKEY(@_);
  134.     my @keys;
  135.  
  136.     while (defined $key) {
  137.     push @keys, $key;
  138.     $key = $self->NEXTKEY(@_, $key);
  139.     }
  140.     foreach $key (@keys) {
  141.     $self->DELETE(@_, $key);
  142.     }
  143. }
  144.  
  145. # The Tie::StdHash package implements standard perl hash behaviour.
  146. # It exists to act as a base class for classes which only wish to
  147. # alter some parts of their behaviour.
  148.  
  149. package Tie::StdHash;
  150. @ISA = qw(Tie::Hash);
  151.  
  152. sub TIEHASH  { bless {}, $_[0] }
  153. sub STORE    { $_[0]->{$_[1]} = $_[2] }
  154. sub FETCH    { $_[0]->{$_[1]} }
  155. sub FIRSTKEY { my $a = scalar keys %{$_[0]}; each %{$_[0]} }
  156. sub NEXTKEY  { each %{$_[0]} }
  157. sub EXISTS   { exists $_[0]->{$_[1]} }
  158. sub DELETE   { delete $_[0]->{$_[1]} }
  159. sub CLEAR    { %{$_[0]} = () }
  160.  
  161. 1;
  162.