NAME

       AptPkg::hash - a helper class for implementing tied hashes

SYNOPSIS

       use AptPkg::hash;

DESCRIPTION

       The AptPkg::hash class provides hash-like access for objects which have an underlying XS
       implementation.

       Such objects need to add AptPkg::hash to @ISA, provide get, set and exists methods, and an
       iterator class.

   AptPkg::hash
       new([XS_OBJECT])
           Create a object as a tied hash.  The object is implemented as a hash reference blessed
           into the class, which in turn is tied to AptPkg::hash.

           This means that both $obj->method() and $obj->{key} valid, the latter invoking get/set
           (through FETCH/STORE).

           The tie associates an array reference with the hash, which initially contains a
           reference to the hash, the XS object and an anon hash which may be used by subclasses
           to store state information.

           If no XS object is passed, one is created via new in the XS class.  The name of that
           class is constructed from the class name, by lower-casing the last component and
           prefixing it with an underscore (eg. AptPkg::Config becomes AptPkg::_config).

           If the module contains a @KEYS array, then the private hash will be populated with
           those entries as keys (see the description below of the AptPkg::hash::method class).

       _self, _xs, _priv
           Accessors which may be used in subclass methods to fetch the three array elements
           associated with the hash reference.

       keys(ARGS)
           In a scalar context, creates and returns a new iterator object (the class name with
           the suffix ::Iter appended).

           The XS object, the private hash and any arguments are passed to the constructor.

           In an array context, the iterator is used to generate a list of keys which are then
           returned.

           The iterator class must implement a next method, which returns the current key and
           advances to the next.

   AptPkg::hash::method
       The AptPkg::hash::method class extends AptPkg::hash, providing a simple way to map a fixed
       set of keys (defined by the @KEYS array) into method calls on either the object, or the
       internal XS object.

       Classes inheriting from AptPkg::hash::method should provide an iterator class which
       inherits from AptPkg::hash::method::iter.

AUTHOR

       Brendan O'Dea <bod@debian.org>