in reply to RFC: Proofread POD for my main random module, please? (more)
Changes
- Broadened examples.
- Example usage with each section of POD.
- tiny_rand and instant_rand now aliases for random_from_list (name suggested by pryrt and seconded by Marshall, though hippo suggested another name).
- Current name restored, though I am still interested in help on renaming it.
About the names tiny_rand and instant_rand and why tiny_rand wasn't just expanded when I came up with instant_rand, they seemed like good idea at the time. On reflection, they are not. So your suggestions were taken and used. However, random_from_list doesn't flow out of the fingertips as quickly as tiny_rand does.
pryrt, when you said don't quote undef, please know I didn't "quote" anything. I used the C<> POD markup around the words that are quoted in perldoc view. So C<undef> becomes "undef" in the perldoc viewer. In CPAN's POD checker there are no quotes unless I typed them into the POD.
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;
|
---|
Replies are listed 'Best First'. | |
---|---|
Re^2: RFC: Proofread POD for my main random module, please? (more)
by hippo (Bishop) on Jun 02, 2017 at 08:14 UTC | |
Re^2: RFC: Proofread POD for my main random module, please? (more)
by pryrt (Abbot) on Jun 02, 2017 at 13:31 UTC | |
Re^2: RFC: Proofread POD for my main random module, please? (more)
by Lady_Aleena (Priest) on Jun 04, 2017 at 22:03 UTC |