mingw/html/lib/Tie/Hash.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Tie::ExtraHash - base class definitions for tied hashes</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Tie::ExtraHash - base class definitions for tied hashes</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#inheriting_from_tie__stdhash">Inheriting from <strong>Tie::StdHash</strong></a></li>
  26         <li><a href="#inheriting_from_tie__extrahash">Inheriting from <strong>Tie::ExtraHash</strong></a></li>
  27         <li><a href="#scalar__untie_and_destroy"><code>SCALAR</code>, <code>UNTIE</code> and <code>DESTROY</code></a></li>
  28         <li><a href="#more_information">MORE INFORMATION</a></li>
  29 </ul>
  30 <!-- INDEX END -->
  31
  32 <hr />
  33 <p>
  34 </p>
  35 <h1><a name="name">NAME</a></h1>
  36 <p>Tie::Hash, Tie::StdHash, Tie::ExtraHash - base class definitions for tied hashes</p>
  37 <p>
  38 </p>
  39 <hr />
  40 <h1><a name="synopsis">SYNOPSIS</a></h1>
  41 <pre>
  42     package NewHash;
  43     require Tie::Hash;</pre>
  44 <pre>
  45     @ISA = (Tie::Hash);</pre>
  46 <pre>
  47     sub DELETE { ... }          # Provides needed method
  48     sub CLEAR { ... }           # Overrides inherited method</pre>
  49 <pre>
  50     package NewStdHash;
  51     require Tie::Hash;</pre>
  52 <pre>
  53     @ISA = (Tie::StdHash);</pre>
  54 <pre>
  55     # All methods provided by default, define only those needing overrides
  56     # Accessors access the storage in %{$_[0]};
  57     # TIEHASH should return a reference to the actual storage
  58     sub DELETE { ... }</pre>
  59 <pre>
  60     package NewExtraHash;
  61     require Tie::Hash;</pre>
  62 <pre>
  63     @ISA = (Tie::ExtraHash);</pre>
  64 <pre>
  65     # All methods provided by default, define only those needing overrides
  66     # Accessors access the storage in %{$_[0][0]};
  67     # TIEHASH should return an array reference with the first element being
  68     # the reference to the actual storage
  69     sub DELETE {
  70       $_[0][1]-&gt;('del', $_[0][0], $_[1]); # Call the report writer
  71       delete $_[0][0]-&gt;{$_[1]};           #  $_[0]-&gt;SUPER::DELETE($_[1])
  72     }</pre>
  73 <pre>
  74     package main;</pre>
  75 <pre>
  76     tie %new_hash, 'NewHash';
  77     tie %new_std_hash, 'NewStdHash';
  78     tie %new_extra_hash, 'NewExtraHash',
  79         sub {warn &quot;Doing \U$_[1]\E of $_[2].\n&quot;};</pre>
  80 <p>
  81 </p>
  82 <hr />
  83 <h1><a name="description">DESCRIPTION</a></h1>
  84 <p>This module provides some skeletal methods for hash-tying classes. See
  85 <a href="file://C|\msysgit\mingw\html/pod/perltie.html">the perltie manpage</a> for a list of the functions required in order to tie a hash
  86 to a package. The basic <strong>Tie::Hash</strong> package provides a <code>new</code> method, as well
  87 as methods <code>TIEHASH</code>, <code>EXISTS</code> and <code>CLEAR</code>. The <strong>Tie::StdHash</strong> and
  88 <strong>Tie::ExtraHash</strong> packages
  89 provide most methods for hashes described in <a href="file://C|\msysgit\mingw\html/pod/perltie.html">the perltie manpage</a> (the exceptions
  90 are <code>UNTIE</code> and <code>DESTROY</code>).  They cause tied hashes to behave exactly like standard hashes,
  91 and allow for selective overwriting of methods.  <strong>Tie::Hash</strong> grandfathers the
  92 <code>new</code> method: it is used if <code>TIEHASH</code> is not defined
  93 in the case a class forgets to include a <code>TIEHASH</code> method.</p>
  94 <p>For developers wishing to write their own tied hashes, the required methods
  95 are briefly defined below. See the <a href="file://C|\msysgit\mingw\html/pod/perltie.html">the perltie manpage</a> section for more detailed
  96 descriptive, as well as example code:</p>
  97 <dl>
  98 <dt><strong><a name="item_tiehash_classname_2c_list">TIEHASH classname, LIST</a></strong>
  99
 100 <dd>
 101 <p>The method invoked by the command <code>tie %hash, classname</code>. Associates a new
 102 hash instance with the specified class. <code>LIST</code> would represent additional
 103 arguments (along the lines of <a href="file://C|\msysgit\mingw\html/lib/AnyDBM_File.html">the AnyDBM_File manpage</a> and compatriots) needed to
 104 complete the association.</p>
 105 </dd>
 106 </li>
 107 <dt><strong><a name="item_store_this_2c_key_2c_value">STORE this, key, value</a></strong>
 108
 109 <dd>
 110 <p>Store datum <em>value</em> into <em>key</em> for the tied hash <em>this</em>.</p>
 111 </dd>
 112 </li>
 113 <dt><strong><a name="item_fetch_this_2c_key">FETCH this, key</a></strong>
 114
 115 <dd>
 116 <p>Retrieve the datum in <em>key</em> for the tied hash <em>this</em>.</p>
 117 </dd>
 118 </li>
 119 <dt><strong><a name="item_firstkey_this">FIRSTKEY this</a></strong>
 120
 121 <dd>
 122 <p>Return the first key in the hash.</p>
 123 </dd>
 124 </li>
 125 <dt><strong><a name="item_nextkey_this_2c_lastkey">NEXTKEY this, lastkey</a></strong>
 126
 127 <dd>
 128 <p>Return the next key in the hash.</p>
 129 </dd>
 130 </li>
 131 <dt><strong><a name="item_exists_this_2c_key">EXISTS this, key</a></strong>
 132
 133 <dd>
 134 <p>Verify that <em>key</em> exists with the tied hash <em>this</em>.</p>
 135 </dd>
 136 <dd>
 137 <p>The <strong>Tie::Hash</strong> implementation is a stub that simply croaks.</p>
 138 </dd>
 139 </li>
 140 <dt><strong><a name="item_delete_this_2c_key">DELETE this, key</a></strong>
 141
 142 <dd>
 143 <p>Delete the key <em>key</em> from the tied hash <em>this</em>.</p>
 144 </dd>
 145 </li>
 146 <dt><strong><a name="item_clear_this">CLEAR this</a></strong>
 147
 148 <dd>
 149 <p>Clear all values from the tied hash <em>this</em>.</p>
 150 </dd>
 151 </li>
 152 <dt><strong><a name="item_scalar_this">SCALAR this</a></strong>
 153
 154 <dd>
 155 <p>Returns what evaluating the hash in scalar context yields.</p>
 156 </dd>
 157 <dd>
 158 <p><strong>Tie::Hash</strong> does not implement this method (but <strong>Tie::StdHash</strong>
 159 and <strong>Tie::ExtraHash</strong> do).</p>
 160 </dd>
 161 </li>
 162 </dl>
 163 <p>
 164 </p>
 165 <hr />
 166 <h1><a name="inheriting_from_tie__stdhash">Inheriting from <strong>Tie::StdHash</strong></a></h1>
 167 <p>The accessor methods assume that the actual storage for the data in the tied
 168 hash is in the hash referenced by <code>tied(%tiedhash)</code>.  Thus overwritten
 169 <code>TIEHASH</code> method should return a hash reference, and the remaining methods
 170 should operate on the hash referenced by the first argument:</p>
 171 <pre>
 172   package ReportHash;
 173   our @ISA = 'Tie::StdHash';</pre>
 174 <pre>
 175   sub TIEHASH  {
 176     my $storage = bless {}, shift;
 177     warn &quot;New ReportHash created, stored in $storage.\n&quot;;
 178     $storage
 179   }
 180   sub STORE    {
 181     warn &quot;Storing data with key $_[1] at $_[0].\n&quot;;
 182     $_[0]{$_[1]} = $_[2]
 183   }</pre>
 184 <p>
 185 </p>
 186 <hr />
 187 <h1><a name="inheriting_from_tie__extrahash">Inheriting from <strong>Tie::ExtraHash</strong></a></h1>
 188 <p>The accessor methods assume that the actual storage for the data in the tied
 189 hash is in the hash referenced by <code>(tied(%tiedhash))-&gt;[0]</code>.  Thus overwritten
 190 <code>TIEHASH</code> method should return an array reference with the first
 191 element being a hash reference, and the remaining methods should operate on the
 192 hash <code>%{ $_[0]-&gt;[0] }</code>:</p>
 193 <pre>
 194   package ReportHash;
 195   our @ISA = 'Tie::ExtraHash';</pre>
 196 <pre>
 197   sub TIEHASH  {
 198     my $class = shift;
 199     my $storage = bless [{}, @_], $class;
 200     warn &quot;New ReportHash created, stored in $storage.\n&quot;;
 201     $storage;
 202   }
 203   sub STORE    {
 204     warn &quot;Storing data with key $_[1] at $_[0].\n&quot;;
 205     $_[0][0]{$_[1]} = $_[2]
 206   }</pre>
 207 <p>The default <code>TIEHASH</code> method stores ``extra'' arguments to <code>tie()</code> starting
 208 from offset 1 in the array referenced by <code>tied(%tiedhash)</code>; this is the
 209 same storage algorithm as in TIEHASH subroutine above.  Hence, a typical
 210 package inheriting from <strong>Tie::ExtraHash</strong> does not need to overwrite this
 211 method.</p>
 212 <p>
 213 </p>
 214 <hr />
 215 <h1><a name="scalar__untie_and_destroy"><code>SCALAR</code>, <code>UNTIE</code> and <code>DESTROY</code></a></h1>
 216 <p>The methods <code>UNTIE</code> and <code>DESTROY</code> are not defined in <strong>Tie::Hash</strong>,
 217 <strong>Tie::StdHash</strong>, or <strong>Tie::ExtraHash</strong>.  Tied hashes do not require
 218 presence of these methods, but if defined, the methods will be called in
 219 proper time, see <a href="file://C|\msysgit\mingw\html/pod/perltie.html">the perltie manpage</a>.</p>
 220 <p><code>SCALAR</code> is only defined in <strong>Tie::StdHash</strong> and <strong>Tie::ExtraHash</strong>.</p>
 221 <p>If needed, these methods should be defined by the package inheriting from
 222 <strong>Tie::Hash</strong>, <strong>Tie::StdHash</strong>, or <strong>Tie::ExtraHash</strong>. See <em>pertie/``SCALAR''</em>
 223 to find out what happens when <code>SCALAR</code> does not exist.</p>
 224 <p>
 225 </p>
 226 <hr />
 227 <h1><a name="more_information">MORE INFORMATION</a></h1>
 228 <p>The packages relating to various DBM-related implementations (<em>DB_File</em>,
 229 <em>NDBM_File</em>, etc.) show examples of general tied hashes, as does the
 230 <a href="file://C|\msysgit\mingw\html/lib/Config.html">the Config manpage</a> module. While these do not utilize <strong>Tie::Hash</strong>, they serve as
 231 good working examples.</p>
 232 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 233 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 234 <big><strong><span class="block">&nbsp;Tie::ExtraHash - base class definitions for tied hashes</span></strong></big>
 235 </td></tr>
 236 </table>
 237
 238 </body>
 239
 240 </html>