https://github.com/kentnl/set-associate

Pick items from a dataset associatively
https://github.com/kentnl/set-associate

Last synced: 4 days ago
JSON representation

Pick items from a dataset associatively

• Host: GitHub
• URL: https://github.com/kentnl/set-associate
• Owner: kentnl
• License: other
• Created: 2013-01-24T08:33:04.000Z (almost 12 years ago)
• Default Branch: master
• Last Pushed: 2017-03-07T10:06:07.000Z (over 7 years ago)
• Last Synced: 2023-08-20T22:51:49.754Z (about 1 year ago)
• Language: Perl
• Size: 297 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.mkdn
  • Changelog: Changes
  • Contributing: CONTRIBUTING.pod
  • License: LICENSE

Awesome Lists containing this project

README

        
# 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](https://metacpan.org/pod/Set::Associate::NewKey#linear_wrap)

`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 

# COPYRIGHT AND LICENSE

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