NAME Set::Associate - Pick items from a dataset associatively VERSION version 0.001000 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 * pool selection 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 COPYRIGHT AND LICENSE This software is copyright (c) 2013 by Kent Fredric . This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.