NAME

HashFiller - Programatically fill elements of a hash based in prerequisites

SYNOPSIS

  use Hash::Filler;

  my $hf = new Hash::Filler;

  $hf->add('key1', sub { my $hr = shift; ... }, ['key2', 'key3'], $pref);
  $hf->add('key1', sub { my $hr = shift; ... }, [], $pref);
  $hf->add('key2', sub { my $hr = shift; ... }, ['key1', 'key3'], $pref);
  $hf->add('key3', sub { my $hr = shift; ... }, ['key1', 'key2'], $pref);

  $hf->loop(0);			# Don't try to avoid infinite loops

				# Test if a key exists using defined()
  $hf->method($Hash::Filler::DEFINED);

  my %hash;

  $hf->fill(\%hash, 'key1');	# Calculate the value of $hash{key1}
  $hash{'key2'} = 'foo';	# Manually fill a hash position
  $hf->fill(\%hash, 'key2');	# Calculate the value of $hash{key2}

DESCRIPTION

Hash::Filler provides an interface so that hash elements can be calculated depending in the existence of other hash elements, using user-supplied code references.

There are a few relevant methods, described below:

->add($key, $code, $r_prereq, $pref)

Adds a new rule to the Hash::Filler object. The rule will be used to fill the hash bucket identified with key $key. To fill this bucket, the code referenced by $code will be invoked, passing it a reference to the hash being worked on and the key that is being filled. This will only be called if all of the hash buckets whose keys are in the list referenced by $r_prereq exist.

If the user-supplied code returns a false value, failure is assumed.

An optional preference can be supplied. This is used to help the internal rule selection choose the better rule.

Multiple rules for the same $key and the same $r_prereq can be added. The module will attempt to use them both but the execution order will be undefined unless you use $pref. The default $pref is 100.

->method($val)

Which method to use to decide if a given key is present in the hash. The accepted values are:

$Hash::Filler::EXISTS (default)

The existence of a hash element or key is calculated using a
construct like C<exists($hash{$key})>.

$Hash::Filler::DEFINED

The existence of a hash element or key is calculated using a
construct like C<defined($hash{$key})>.

$Hash::Filler::TRUE

The existence of a hash element or key is calculated using a
construct like C<$hash{$key}>.

This allow this module to be customized to the particular application in which it is being used. Be advised that changing this might cause a change in which and when the rules are invoked for a particular hash so probably it should only be used before the first call to ->fill.

By defult, the module uses exists() to do this check.

->loop($val)

Controls if the module should try to avoid infinite loops. A true $val means that it must try (the default). A false value means otherwise.

->fill($r_hash, $key)

Attempts to fill the bucket $key of the hash referenced by $r_hash using the supplied rules.

This method will return a true value if there are rules that allow the requested $key to be calculated (or the $key is in the hash) and the user supplied code returned true.

To avoid infinite loops, the code will not invoke a rule twice unless ->loop is called with a true value. The rules will be used starting with the ones with less prerequisites, as these are assumed to be lighter. To use a different ordering, specify $pref. Higher values of $pref are used first.

CAVEATS

This code uses recursion to resolve rules. This allows it to figure out the value for a given key with only an incomplete rule specification. Be warned that this might be costly if used with large sets of rules.

AUTHOR

Luis E. Munoz < lem@cantv.net>

SEE ALSO

perl(1).

WARRANTY

Absolutely none.