Lady_Aleena has asked for the wisdom of the Perl Monks concerning the following question:

Hello. Would some gentle monks please proofread my POD for my main random module and let me know if it makes sense?

Also, I would love some help renaming the module. It is currently sitting at RolePlaying::Random. I am moving most of my random generation modules to Random::. If one day I decide to share my randomness with CPAN, I do not feel I can take the top spot in the Random name space for this module. It would not be right unless I get a whole lot of people from here and CPAN telling me it is okay. I am leaning toward Random::util, but I am not sure of it. What do you name modules that you use to build other modules?

Please let me know if you see something in the code that needs improvement, too.

Thank you in advence!

Update 1: From the responses, I made changes that can be found here.

Update 2: From the additional responses, I made more changes that can be found here.

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\t +Stopped$!" } 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 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. sub random_color { my ($color_key, $color_additions) = @_; random($color_hash, $color_key, { caller => 'random_color', additi +ons => $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 th +e selected key. =head3 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. =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 sub +routine your are using random in. From the example above, if the user chooses a list that will not produ +ce 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;

I did not realize until I posted this how long the pod got.

No matter how hysterical I get, my problems are not time sensitive. So, relax, have a cookie, and a very nice day!
Lady Aleena