package 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} ? " from ".$opt->{caller} : '';
      die "Your option $user_input does not produce 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 tiny_rand { 
  my ($var1, $var2) = @_;
  return ($var1, $var2)[rand 2];
}

sub instant_rand {
  my @rand_array = @_;
  return $rand_array[rand @rand_array];
}

=head1 NAME

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

=head1 SYNOPSIS

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

  my $random_thing = random($hash_of_arrays, $list, $options);
  
  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.

  sub random_color {
    my ($color_key, $color_additions) = @_;
    random($color_hash, $color_key, { caller => 'random_color', additions => $color_additions});
  }

=head3 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.

=head3 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.

=head3 by keys

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

=head3 a key

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

=head3 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.

=head3 options

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

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

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

From the example above, if the user chooses a list that will not produce a result, the error message will read as follows.

  Your option list does not produce a list from random_color.
    Stopped at ...

=head2 tiny_rand

C<tiny_rand> takes an array of two items and returns a random result.

=head2 instant_rand

C<instant_rand> takes an array of any size and returns a random result.

=head1 AUTHOR

Lady Aleena

=cut

1;