NAME
Tie::TwoLevelHash - Tied interface to multi-dimensional (Two-Level) hash files
SYNOPSIS
# Tie to Hash-o-hashes
use Tie::TwoLevelHash;
tie (%hash, 'Tie::TwoLevelHash', $file, 'rw'); # Open in read/write mode
$hash{PEOPLE} = {YOU => "me"}; # Set value YOU in hash PEOPLE withing hash %hash to "me"
# Tie to hash B<within> a Hash-o-hashes
use Tie::TwoLevelHash:
tie (%hash, 'Tie::TwoLevelHash', "$file, <SingHash>" 'rw'); # Open in read/write mode
$hash{YOU} = "me"; # Set key YOU in hash <SingHash> (within HoH's) to "me"
untie %hash;
tie (%hash, 'Tie::TwoLevelHash', $file); # Defaults to read-only modeDESCRIPTION
This is the Tie::TwoLevelHash module. It is a TIEHASH interface which lets you tie to a text file which is a multi-dimensional (two level) hash.
To use it, tie a hash to a directory:
tie(%hash, 'Tie::TwoLevelHash', $file, 'rw'); # Open in read/write modeIf you pass 'rw' as the third parameter, you'll be in read/write mode, and any changes you make to the hash will create or modify the file. If you don't open in read/write mode you'll be in read-only mode, and any changes you make to the hash won't have any effect in the given file. It's actually useless to tie to the file in read mode and make write calls to it, or the hash you are tying to it. If you do, it may croak, depending on what you are trying. If you want to grab values and play with them, do that in your script, and get the values out of the hash name you are tying with, so you can write to a local hash, and not affect, or try to affect the hash you are tying with.
Two Level Hash Files
A two level hash file (I use a .tlh extension) is a file after the same format as the defunct(?) Windows .ini files. A simple example of a small TLH file is as follows:
# This is a TLH file
# Comments on top of this file are allowed
COLORS
Red: #ff0000
Black: #000000
White: #ffffff
PEOPLE
Dog: Zeke
Cat: Tigger
PerlHacker: Randal
Author: Kevin Meltzer
EXTRA
Key: Val
Test: VestThis file is a textual representation of a two-level hash, also known as a Hash of hashes. The file itself is the main hash, and each section contains another hash. So, this file contains the hash COLORS the hash PEOPLE and the hash EXTRA. Tie::TwoLevelHash allows for you to tie to the entire hash of hashes, or directly to one of the hashes within that hash of hashes. When you make a change in your script to the tied hash, it makes that change in your file.
EXAMPLES
Tying to hash of hashes
$file = "foo.tlh";
tie(%hash, 'Tie::TwoLevelHash', $file, 'rw');
# Set existing value
$hash{PEOPLE} = {You => "me"};
# Set new value
$hash{COLORS} = {YELLOW => "flowery"};
# Set new record
$hash{HATS} = {BLACK => "Cowboy", RED => "Baseball", WHITE => "Beanie"};
# Add new record with predefined hash
%new = (ONE => "1",
TWO => "2",
THREE => "3",
FOUR => "4",
);
$hash{NUM} = {%new}; # Works, or can use \%new instead of {%new}
# Clear, set then delete entry
$hash{PEOPLE} = {FOO => ""};
$hash{PEOPLE} = {FOO => "Bar"};
$hash{PEOPLE} = {FOO => undef};
# Added new element to existing record
$hash{PEOPLE} = {'FOO' => "FOObar"};
$hash{EXTRA} = undef;
untie %hash;
The resulting TLH file would be (assuming you began with the TLH example above):
# This is a TLH file
# Comments on top of this file are allowed
COLORS
Black: #000000
Red: #ff0000
White: #ffffff
Yellow: flowery
HATS
BLACK: Cowboy
RED: Baseball
WHITE: Pope hat
NUM
FOUR: 4
ONE: 1
THREE: 3
TWO: 2
PEOPLE
Author: Kevin Meltzer
Cat: Tigger
Dog: Zeke
FOO: FOObar
PerlHacker: RandalTying to a hash within a hash of hashes
tie(%hash, 'TwoLevelHash', "$file, PEOPLE", 'rw');
# Set existing value
$hash{Cat} = "Gizmo";
# Set new value
$hash{Someone} = "Larry";
# Clear, set then delete entry
$hash{FOO} = "";
$hash{FOO} = "bar";
$hash{FOO} = undef;
untie %hash;The resulting TLH file would be:
# This is a TLH file
# Comments on top of this file are allowed
COLORS
Red: #ff0000
Black: #000000
White: #ffffff
PEOPLE
Author: Kevin Meltzer
Cat: Gizmo
Dog: Zeke
PerlHacker: Randal
Someone: Larry
EXTRA
Key: Val
Test: VestCHANGING VALUES
I won't go into how to change value in a hash. When you are tying to a hash in the hash of hashes, you make your calls as usual. You make your calls as usual when you are tied to the entire HoH's, except when you are setting new values (anything that would call STORE).
Due to tie() not being very friendly while tying to HoH's, you can not make a call such as $hash{FOO}->{BAR} = "zog"; when tied to a HoH's. So, you must make this call like: $hash{FOO} = {BAR => "zog"};
You can see how/when to do this in the EXAMPLE section. When you want to delete a key in a hash, use undef like: $hash{FOO} = {BAR => undef}; or, when tying to single hash: $hash{BAR} = undef;
%hash = (); This will CLEAR the hash, as well as remove ALL data from the file you are tied to. Be sure you want to do this when you call it.
INSTALLATION
You install Tie::TwoLevelHash, as you would install any perl module library, by running these commands:
perl Makefile.PL
make
make test
make install
make cleanAUTHOR
Copyright 1998, Kevin Meltzer. All rights reserved. It may be used and modified freely, but I do request that this copyright notice remain attached to the file. You may modify this module as you wish, but if you redistribute a modified version, please attach a note listing the modifications you have made.
Address bug reports and comments to: kmeltz@cris.com
The author makes no warranties, promises, or gaurentees of this software. As with all software, use at your own risk.
VERSION
Version 1.0 19 Oct 1998
AVAILABILITY
The latest version of Tie::TwoLevelHash should always be available from:
$CPAN/modules/by-authors/id/K/KM/KMELTZ/Visit <URL:http://www.perl.com/CPAN/> to find a CPAN site near you.
ACK's
Milivoj Ivkovic [mi@alma.ch]
Joshua Chamas [chamas@alumni.stanford.org]
Matthew Sergeant (EML) [Matthew.Sergeant@eml.ericsson.se]
Thanks to these people for sharing idea's and/or prodding me to make this module better.
SEE ALSO
perl(1), perlfunc(1), perltie(1)