Session hash tools.

The functions in this package are designed to get or set individual values in
PL/Perl global hash. They support 3 levels of nesting, meaning that you can
create hashes and subhashes (more correctly hash references) as elements of a 
$_GLOBAL hash as well as individual records.

WARNING: since %_GLOBAL hash is not shared between PL/Perl and PL/PerlU
instances you won't have access to the values set by these functions from
untrusted PL/Perl. You can, of course, 'fix' this by changing the language of
the functions from plperl to plperlu, however, you can't have access to the
same hash values from both trusted and untrusted versions of PL/Perl.

This work is sponsored by Enova Financial (http://enovafinancial.com)

Installation:

make && make install.

Start the $dbname 
createlang plperl $dbname
psql -c "CREATE SCHEMA tools" $dbname
psql -f $PGDATA/share/contrib/tools.sql $dbname

Usage:

There are 3 functions for each get or set operation. The first one takes 2
arguments and creates 'nested' hashes. The second is one-argument and deals
with values directly in the %_GLOBAL hash, and the last one provides 2-level
nesting for the hashes, i.e.

tools.session__set(key1 TEXT, key2 TEXT, value TEXT) equals to
%_GLOBAL{$key1}{$key2} = $value 

tools.session__set(key TEXT, value TEXT) is 
%_GLOBAL{$key} = $value

tools.session__set(key1 TEXT, key2 TEXT, key3 TEXT, value TEXT) equals to
%_GLOBAL{$key1}{$key2}{$key3} = $value

if value argument is NULL then the corresponding key is cleared from the
%_GLOBAL hash.

Corresponding get functions are:

tools.session__get(key1 TEXT, key2 TEXT) 
tools.session__get(key TEXT)
tools.session__get(key1 TEXT, key2 TEXT, key3 TEXT) 


Note that undef is returned if the key is missing in the hash. Also
accessing the hash value with function that takes more or less arguments
than there are hash keys will result in error message.

To clear hash keys en masse use tools.session__clean(mode TEXT, keys TEXT),
where mode can be either 'keep' or 'delete', and keys are the comma-separated
string of key names, i.e.

tools.session__clean('delete', 'a, b, c, d')

removes keys from 'a' to 'd' from the %_GLOBAL hash. Note that only keys in
%_GLOBAL itself are removed with this function, to remove a subkey in a nested
hash use session__set with NULL as the value argument.

To remove all keys from the hash call tools.session__reset().

Finally, to display all %_GLOBAL hash keys (including nested ones) use
tools.session__list();