NAME

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

VERSION

version 0.004001

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.