Kent Fredric > Set-Associate-0.001001 > Set::Associate

Download:
Set-Associate-0.001001.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.001001   Source   Latest Release: Set-Associate-0.003000

NAME ^

Set::Associate - Pick items from a dataset associatively

VERSION ^

version 0.001001

DESCRIPTION ^

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

The most simple usage of this code gives out values from items seqeuntially, and remembers seen values and persists them within the scope of the program, ie:

    my $set = Set::Associate->new(
        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(
        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(
        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(
        items => [qw( red blue yellow )],
        on_items_empty => Set::Associate::RefillItems::shuffle,
    );

IMPLEMENTATION DETAILS ^

There are 2 Main phases that occur within this code

Pool Population

The pool of available options ( _items_cache ) is initialised 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.

The default implementation copies items from items 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 ^

items

    required ArrayRef[ Any ]

on_items_empty

    lazy Set::Associate::RefillItems = Set::Associate::RefillItems::linear

on_new_key

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

METHODS ^

items_elements

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 ^

items

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 );

PRIVATE CONSTRUCTOR ARGUMENTS ^

_items_cache

    lazy ArrayRef[ Any ] = [ ]

_association_cache

    lazy HashRef[ Any ] = { }

PRIVATE METHODS ^

_items_cache_empty

_items_cache_shift

_items_cache_push

_items_cache_count

_items_cache_get

_association_cache_has

    if ( $sa->_assocition_cache_has( $key ) ){
        return $sa->_association_cache_get( $key );
    }

_association_cache_get

    my $assocval = $sa->_association_cache_get( $key );

_association_cache_set

    $sa->_association_cache_set( $key, $assocval );

PRIVATE ATTRIBUTES ^

_items_cache

_association_cache

    my $cache = $sa->_association_cache();
    $cache->{ $key } = $value;

AUTHOR ^

Kent Fredric <kentfredric@gmail.com>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2013 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.

syntax highlighting: