Tie::Hash

Section: Perl Programmers Reference Guide (3perl)
Updated: 2001-02-22
Index
Return to Main Contents

NAME

Tie::Hash, Tie::StdHash - base class definitions for tied hashes

SYNOPSIS

    package NewHash;
    require Tie::Hash;

    @ISA = (Tie::Hash);

    sub DELETE { ... }          # Provides needed method
    sub CLEAR { ... }           # Overrides inherited method

    package NewStdHash;
    require Tie::Hash;

    @ISA = (Tie::StdHash);

    # All methods provided by default, define only those needing overrides
    sub DELETE { ... }

    package main;

    tie %new_hash, 'NewHash';
    tie %new_std_hash, 'NewStdHash';

DESCRIPTION

This module provides some skeletal methods for hash-tying classes. See perltie for a list of the functions required in order to tie a hash to a package. The basic Tie::Hash package provides a "new" method, as well as methods "TIEHASH", "EXISTS" and "CLEAR". The Tie::StdHash package provides most methods required for hashes in perltie. It inherits from Tie::Hash, and causes tied hashes to behave exactly like standard hashes, allowing for selective overloading of methods. The "new" method is provided as grandfathering in the case a class forgets to include a "TIEHASH" method.

For developers wishing to write their own tied hashes, the required methods are briefly defined below. See the perltie section for more detailed descriptive, as well as example code:

TIEHASH classname, LIST: The method invoked by the command "tie %hash, classname". Associates a new hash instance with the specified class. "LIST" would represent additional arguments (along the lines of AnyDBM_File and compatriots) needed to complete the association.
STORE this, key, value: Store datum value into key for the tied hash this.
FETCH this, key: Retrieve the datum in key for the tied hash this.
FIRSTKEY this: Return the (key, value) pair for the first key in the hash.
NEXTKEY this, lastkey: Return the next key for the hash.
EXISTS this, key: Verify that key exists with the tied hash this.
The Tie::Hash implementation is a stub that simply croaks.
DELETE this, key: Delete the key key from the tied hash this.
CLEAR this: Clear all values from the tied hash this.

CAVEATS

The perltie documentation includes a method called "DESTROY" as a necessary method for tied hashes. Neither Tie::Hash nor Tie::StdHash define a default for this method. This is a standard for class packages, but may be omitted in favor of a simple default.

MORE INFORMATION

The packages relating to various DBM-related implementations (DB_File, NDBM_File, etc.) show examples of general tied hashes, as does the Config module. While these do not utilize Tie::Hash, they serve as good working examples.

This document was created by man2html, using the manual pages.
Time: 11:52:28 GMT, April 20, 2024