I hope the expanded examples help, though the POD is now so very very long for such short code.
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, { additio
+ns => [@additional_items], caller => $caller });
my $tiny_rand = tiny_rand(qw(black white));
my $instant_rand = instant_rand(qw(red yellow green cyan blue magent
+a));
=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 creati
+on 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_addit
+ions, caller => 'random_color' });
}
=head3 Selections
=head4 all or nothing
When C<all> or C<undef> is selected or nothing is entered, C<random> w
+ill 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 l
+ists.
=head4 a key
When a specific key is selected, C<random> will return an item from th
+e 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', 'r
+ainbow']>.
=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 li
+sted.
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<call
+er>.
=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 sub
+routine your are using random in.
Using C<random> by itself:
my $random_color = random(\%colors, 'rainboe', { caller => 'random_c
+olor' });
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 m
+essage 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 gr
+een cyan blue magenta));
my $tiny_rand = tiny_rand(qw(black white));
my $instant_rand = instant_rand(qw(red yellow green cyan blue ma
+genta));
=head1 AUTHOR
Lady Aleena
=cut
1;