package RolePlaying::Random;
use strict;
use warnings FATAL => qw(all);
use Exporter qw(import);
our @EXPORT_OK = qw(random tiny_rand instant_rand);

use List::Util qw(shuffle);

sub random {
  my ($list, $user_input, $opt) = @_;
  
  my $random_thing;
  if ($user_input && $user_input =~ /(?:help|options)/) {
    my $keys = join("\n\t", sort keys %{$list});
    $random_thing = "Your options are:
        $keys
        'by keys' to get a random key
        'data' to get the whole hash
        'keys' to get a list of the keys
        'all' to get a random item from any key on the list";
  }
  elsif ($user_input && $user_input eq 'data') {
    $random_thing = $list;
  }
  elsif ($user_input && $user_input eq 'keys') {
    $random_thing = [keys %$list];
  }
  else {
    my @random_list;
    if ($user_input && $user_input eq 'by keys') {
      @random_list = keys %{$list};
    }
    elsif (!$user_input || $user_input eq 'all' ) {
      @random_list = map { @$_ } values %{$list};
    }
    elsif ($list->{$user_input}) {
      @random_list = @{$list->{$user_input}};
    }
    else {
      my $caller = $opt->{caller} ? " in ".$opt->{caller} : '';
      die "Your option '$user_input' is not a list $caller.\n\tStopped$!"
    }
    push @random_list, @{$opt->{'additions'}} if $opt->{'additions'};
    @random_list = shuffle(@random_list);
    $random_thing = $random_list[rand @random_list];
  }
  
  return $random_thing;
}

sub random_from_list {
  my @rand_array = shuffle(@_);
  return $rand_array[rand @rand_array];
}
sub tiny_rand    { random_from_list(@_); }
sub instant_rand { random_from_list(@_); }

=head1 NAME

B<RolePlaying::Random> is a set of tools to generate randomness.

=head1 SYNOPSIS

  use RolePlaying::Random qw(random tiny_rand instant_rand);

  my $random_thing = random($hash_of_arrays, $selected_list, { additions => [@additional_items], caller => $caller });
  
  my $tiny_rand    = tiny_rand(qw(black white));
  my $instant_rand = instant_rand(qw(red yellow green cyan blue magenta));

=head1 DESCRIPTION

B<Random> has three tools to create randomness: C<random>, C<tiny_rand>, and C<instant_rand>.

=head2 random

C<random> takes a hash of arrays and returns a random result based on the list selected from the hash. It is meant to be used in the creation of other random subroutines.

  my %colors = (
    'eye'  => [qw(amber black blue brown gray green hazel red violet)],
    'hair' => [qw(auburn brown black blond gray red white)],
    'rainbow'  => [qw(red orange yellow green blue indigo violet)],  
  );

  sub random_color {
    my ($selected_color_key, $color_additions) = @_;
    random(\%colors, $selected_color_key, {  additions => $color_additions, caller => 'random_color' });
  }

=head3 Selections

=head4 all or nothing

When C<all> or C<undef> is selected or nothing is entered, C<random> will flatten the hash and return any value from the hash.

Using C<random> by itself:

  my $random_color_one = random(\%colors);
  my $random_color_two = random(\%colors, undef);
  my $random_color_all = random(\%colors, 'all');

Using the newly created C<random_color>:

  my $random_color_one = random_color();
  my $random_color_two = random_color(undef);
  my $random_color_all = random_color('all');

All of the above will return any color in the hair, eye, and rainbow lists.

=head4 a key

When a specific key is selected, C<random> will return an item from the selected key.

Using C<random> by itself:

  my $random_hair_color = random(\%colors, 'hair');
  my $random_eyes_color = random(\%colors, 'eye');

Using the newly created C<random_color>:

  my $random_hair_color = random_color('hair');
  my $random_eyes_color = random_color('eye');

=head4 by keys

When C<by keys> is selected, C<random> will return a random key.

Using C<random> by itself:

  my $random_color_key = random(\%colors, 'by keys');

Using the newly created C<random_color>:

  my $random_color_key = random_color('by keys');
  
Both of the above will return a random key from C<%colors>: hair, eye, rainbow.
  
=head4 keys

When C<keys> is selected, C<random> will return the list of keys from the hash to help remind you of your key options.

Using C<random> by itself:

  my $random_color_keys = randon(\%colors, 'keys');

Using the newly created C<random_color>:

  my $random_color_keys = randon_color('keys');

Both of the above will return a list of the keys: C<['hair', 'eye', 'rainbow']>.

=head4 data

When C<data> is selected, C<random> will return the entire hash so you can refresh your memory of what is in the hash.

Using C<random> by itself:

  my $random_color_data = random(\%colors, 'data');

Using the newly created C<random_color>:

  my $random_color_data = random_color('data');

=head4 help or options

When C<help> or C<options> is selected, all of your options will be listed.

Using C<random> by itself:

  my $random_color_help = random(\%colors, 'help');
  my $random_color_opts = random(\%colors, 'options');

Using the newly created C<random_color>:

  my $random_color_help = random_color('help');
  my $random_color_opts = random_color('options');

=head3 Optional parameters

There are two optional parameters you can use, C<additions> and C<caller>.

=head4 additions

C<additions> is a list (arrayref) that you want to add to the list you have already selected.

You might want to add the colors pink, blue, and purple to the choices of hair color or yellow and bloodshot to eye color.

Using C<random> by itself:

  my $random_hair_color = random(\%colors, 'hair', { additions => [qw(pink purple blue)] });
  my $random_eyes_color = random(\%colors, 'eye',  { additions => [qw(yellow bloodshot)] });

Using the newly created C<random_color>:

  my $random_hair_color = random_color('hair', [qw(pink purple blue)]);
  my $random_eyes_color = random_color('eye',  [qw(yellow bloodshot)]);

=head4 caller

C<caller> can be used to create an error message with the specific subroutine your are using random in.

Using C<random> by itself:

  my $random_color = random(\%colors, 'rainboe', { caller => 'random_color' });

Using the newly created C<random_color>:

  my $random_color = random(\%colors, 'rainboe');

If the user selects a list that will not produce a result, the error message from both of the above will read as follows.

  Your option 'rainboe' is not a list in random_color.
    Stopped at ...

=head2 random_from_list

C<random_from_list> takes an array and returns a random result. C<tiny_rand> and C<instant_rand> are aliases for C<random_from_list>.

  my $random_from_list = random_from_list(qw(black white red yellow green cyan blue magenta));
  my $tiny_rand        = tiny_rand(qw(black white));
  my $instant_rand     = instant_rand(qw(red yellow green cyan blue magenta));

=head1 AUTHOR

Lady Aleena

=cut

1;