NAME

Set::Associate - Pick items from a data set associatively

VERSION

version 0.004002

DESCRIPTION

Essentially, this is a simple toolkit to map an infinite-many items to a corresponding finite-many values, i.e: A nick coloring algorithm.

The most simple usage of this code gives out values from items sequentially, and remembers seen values and persists them within the scope of the program, i.e:

my $set = Set::Associate->new(
    on_items_empty => Set::Associate::RefillItems->linear(
        items => [qw( red blue yellow )],
    ),
);
sub color_nick {
    my $nick = shift;
    return colorize( $nick, $set->get_associated( $nick );
}
...
printf '<< %s >> %s', color_nick( $nick ), $message;

And this is extensible to use some sort of persisting allocation method such as a hash

my $set = Set::Associate->new(
    on_items_empty => Set::Associate::RefillItems->linear(
        items => [qw( red blue yellow )],
    ),
    on_new_key => Set::Associate::NewKey->hash_sha1,
);
sub color_nick {
    my $nick = shift;
    return colorize( $nick, $set->get_associated( $nick );
}
...
printf '<< %s >> %s', color_nick( $nick ), $message;

Alternatively, you could use 1 of 2 random forms:

# Can produce colour runs if you're unlucky

my $set = Set::Associate->new(
    on_items_empty => Set::Associate::RefillItems->linear(
        items => [qw( red blue yellow )],
    ),
    on_new_key => Set::Associate::NewKey->random_pick,
);

# Will exhaust the colour variation before giving out the same colour
# twice
my $set = Set::Associate->new(
    on_items_empty => Set::Associate::RefillItems->shuffle(
        items => [qw( red blue yellow )],
    ),
);

IMPLEMENTATION DETAILS

There are 2 Main phases that occur within this code

• pool population
• pool selection

Pool Population

The pool of available options ( _items_cache ) is initialized as an empty list, and every time the pool is being detected as empty ( _items_cache_empty ), the on_items_empty method is called ( run_on_items_empty ) and the results are pushed into the pool.

Pool Selection

Pool selection can either be cherry-pick based, where the pool doesn't shrink, or can be destructive, so that the pool population phase is triggered to replenish the supply of items only when all values have been exhausted.

The default implementation shift's the first item off the queue, allowing the queue to be exhausted and requiring pool population to occur periodically to regenerate the source list.

CONSTRUCTOR ARGUMENTS

on_items_empty

required Set::Associate::RefillItems

on_new_key

lazy Set::Associate::NewKey = Set::Associate::NewKey::linear_wrap

METHODS

run_on_items_empty

if( not @items ){
    push @items, $sa->run_on_items_empty();
}

run_on_new_key

if ( not exists $cache{$key} ){
    $cache{$key} = $sa->run_on_new_key( $key );
}

associate

if( $object->associate( $key ) ) {
    say "already cached";
} else {
    say "new value"
}

get_associated

Generates an association automatically.

my $result = $object->get_associated( $key );

ATTRIBUTES

on_items_empty

my $object = $sa->on_items_empty();
say "Running empty items mechanism " . $object->name;
push @items, $object->run( $sa  );

on_new_key

my $object = $sa->on_new_key();
say "Running new key mechanism " . $object->name;
my $value = $object->run( $sa, $key );

AUTHOR

Kent Fredric kentnl@cpan.org

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Kent Fredric kentfredric@gmail.com.

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