Ricardo SIGNES > Data-Hive-1.008 > Data::Hive



Annotate this POD

View/Report Bugs
Module Version: 1.008   Source   Latest Release: Data-Hive-1.011


Data::Hive - convenient access to hierarchical data


version 1.008


  use Data::Hive;

  my $hive = Data::Hive->NEW(\%arg);


  print $hive->foo->bar->baz->quux->GET;  # 17


Data::Hive doesn't do very much. Its main purpose is to provide a simple, consistent interface for accessing simple, nested data dictionaries. The mechanism for storing or consulting these dictionaries is abstract, so it can be replaced without altering any of the code that reads or writes the hive.

A hive is like a set of nested hash references, but with a few crucial differences:

WHY?? ^

By using method access, the behavior of hives can be augmented as needed during testing or development. Hives can be easily collapsed to single key/value pairs using simple notations whereby $hive->foo->bar->baz->SET(1) becomes $storage->{"foo.bar.baz"} = 1 or something similar.

This, along with the Data::Hive::Store API makes it very easy to swap out the storage and retrieval mechanism used for keeping hives in persistent storage. It's trivial to persist entire hives into a database, flatfile, CGI query, or many other structures, without using weird tricks beyond the weird trick that is Data::Hive itself.


hive path methods

All lowercase methods are used to travel down hive paths.

When you call $hive->some_name, the return value is another Data::Hive object using the same store as $hive but with a starting path of some_name. With that hive, you can descend to deeper hives or you can get or set its value.

Once you've reached the path where you want to perform a lookup or alteration, you call an all-uppercase method. These are detailed below.

hive access methods

These methods are thin wrappers around required modules in Data::Hive::Store subclasses. These methods all basically call a method on the store with the same (but lowercased) name and pass it the hive's path.


This constructs a new hive object. Note that the name is NEW and not new! The new method is just another method to pick a hive path part.

The following are valid arguments for NEW.


a Data::Hive::Store object, or one with a compatible interface; this will be used as the hive's backend storage driver; do not supply store_class or store_args if store is supplied


This names a class from which to instantiate a storage driver. The classname will have Data::Hive::Store:: prepended; to avoid this, prefix it with a '=' (=My::Store). A plus sign can be used instead of an equal sign, for historical reasons.


If store_class has been provided instead of store, this argument may be given as an arrayref of arguments to pass (dereferenced) to the store class's new method.


  my $value = $hive->some->path->GET( $default );

The GET method gets the hive value. If there is no defined value at the path and a default has been supplied, the default will be returned instead.

This method may also be called as GETSTR or GETNUM for backward compatibility, but this is deprecated and will be removed in a future release.


Hives are overloaded for stringification and numification so that they behave like their value when used without an explicit GET. This behavior is deprecated and will be removed in a future release. Always use GET to get the value of a hive.



This method sets (replacing, if necessary) the hive value.

Its return value is not defined.


  if ($hive->foo->bar->EXISTS) { ... }

This method tests whether a value (even an undefined one) exists for the hive.



This method deletes the hive's value. The deleted value is returned. If no value had existed, undef is returned.


This method behaves like DELETE, but all values for paths below the current one will also be deleted.


  my @keys = $hive->KEYS;

This returns a list of next-level path elements that exist. For example, given a hive with values for the following paths:


This shows the expected results:

  keys of      | returns
  foo          | bar, xyz, 123
  foo/bar      | baz
  foo/bar/baz  |
  foo/xyz      | abc, def
  foo/123      |


  $hive->foo->COPY_ONTO( $another_hive->bar );

This method copies all the existing values found at or under the current path to another Data::Hive, using either the same or a different store.

Currently, this will set each found value individually. In the future, store classes should have the ability to receive a bulk-set message to operate in a transaction, if appropriate.


  $hive->HIVE('foo');          #  equivalent to $hive->foo

  $hive->HIVE('foo', 'bar');   #  equivalent to $hive->foo->bar

This method returns a subhive of the current hive. In most cases, it is simpler to use the lowercase hive access method. This method is useful when you must, for some reason, access an entry whose name is not a valid Perl method name.

It is also needed if you must access a path with the same name as a method in UNIVERSAL. In general, only import, isa, and can should fall into this category, but some libraries unfortunately add methods to UNIVERSAL. Common offenders include moniker, install_sub, reinstall_sub.

This method should be needed fairly rarely. It may also be called as ITEM for historical reasons.


This method returns a name that can be used to represent the hive's path. This name is store-dependent, and should not be relied upon if the store may change. It is provided primarily for debugging.


This returns a Data::Hive object for the root of the hive.


This method tells the hive store to save the value (or lack thereof) for the current path. For many stores, this does nothing. For hive stores that are written out only on demand, this method must be called.


This method tells the hive store to save the value (or lack thereof) for the current path and all paths beneath it. For many stores, this does nothing. For hive stores that are written out only on demand, this method must be called.


This method returns the storage driver being used by the hive.



This software is copyright (c) 2006 by Hans Dieter Pearcey.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: