Personally, I think that this is a great improvement over the original and that the examples add much to the clarity of purpose of the module as a whole. Well done.

Now that it's clear (to me) what the module's purpose is, I would suggest changing the nameline from "RolePlaying::Random is a set of tools to generate randomness." to something like "Randomly select values from sets of lists.". I think that this more accurately reflects what the module does. It certainly doesn't generate randomness, that's for a PRNG to perform. What it does is take randomness generated by other code and apply it in various ways to supplied datasets.

random_from_list doesn't flow out of the fingertips as quickly as tiny_rand does.

Maybe not. This helps to illustrate one of the differences between coding for yourself and coding for others. In the latter case, clarity wins every time. Naming your subs (and other symbols such as packages, variables and constants) to follow their purpose helps make the code which others write using them to be legible and maintainable. If you (or anyone) really wants then in their own code to use a shorthand for a sub they can by aliasing or subclassing or whatever. But careful choice of symbol names improves the chances of code being self-documenting and that's a good target to aim at.

FWIW, I seen nothing in this code which ties it to the RolePlaying space. It seems perfectly general. I've just looked around the namespaces and there's neither List::Random nor Random::List. There is, however, Random::Set which seems to perform a similar task but without your bells and whistles. If you think that Random::Set is no more general than your module then maybe consider a more general name for yours. Don't forget PrePAN for soliciting ideas too.

++ Much improved. My point with mentioning "quotes" was I was hoping When C<all> or C<undef> is selected would be When C<'all'> or C<undef> is selected (and similarly for other textual literals, like C<'by keys'> or C<'keys'>). But with the examples that now follow, that's quickly clarified, so it's not critical.

nitpick #1: random_from_list should be included in @EXPORT_OK

nitpick #2: in the =head4 keys section, there are typos of "randon" and "randon_color"

I agree with hippo that List::Random and Random::List both seem to apply as reasonable names. Given Random::Set and Random::Day, which both select a random element from a group, I think I'd have a slight preference for Random::List, because your module complements those nicely. (I agree with your OP, in that taking the top spot of package Random; is not appropriate.) I also ++agree with hippo's Synopsis suggestion.

Don't worry about long POD: in my opinion, long-but-helpful is much better than short-and-unhelpful. As a new user to a module, I want it descriptive enough that someone who doesn't have the author's history with the module would be able to read the documentation and immediately grasp what the module is about and how to use it.

Changes...

• Relocated module from RolePlaying name space to Fancy name space.
• Renamed
  • module from Random to Rand
  • random to fance_rand
  • random_from_list to fancy_rand_from_array (a hash is also a list)
• Corrected errors seen by others.
• Added uniq to the flattened hash list so repeated items don't get more weight.

You might wonder why Fancy::Rand. Well, I already have Fancy::Map, Fancy::Splice, Fancy::Split, Fancy::Join::Defined, and Fancy::Join::Grammatical. I decided when I do something "fancy" with a perl function, I will put it in the name space Fancy and name the top subroutine fancy_function. So, now I can add Fancy::Rand and fancy_rand to my list of Fancy::Functions.

Here is the final rough draft. I think I got everything fixed.

package Fancy::Rand;
use strict;
use warnings FATAL => qw(all);
use Exporter qw(import);
our @EXPORT_OK = qw(fancy_rand fancy_rand_from_array tiny_rand instant
+_rand);

use List::Util qw(shuffle uniq);

sub fancy_rand {
  my ($list, $user_input, $opt) = @_;
  
  my $random_item;
  if ($user_input && $user_input =~ /(?:help|options)/) {
    my $keys = join("\n  ", sort keys %{$list});
    $random_item = "Your options are:
  $keys
  by keys: get a random key
  all: get a random item from any key on the list
  keys: get the list of the keys
  data: get the whole hash";
  }
  elsif ($user_input && $user_input eq 'data') {
    $random_item = $list;
  }
  elsif ($user_input && $user_input eq 'keys') {
    $random_item = [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 = uniq(map { @$_ } values %{$list});
    }
    elsif ($list->{$user_input}) {
      @random_list = @{$list->{$user_input}};
    }
    else {
      my $caller = $opt->{caller} ? " in ".$opt->{caller} : 'fancy_ran
+d';
      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_item = $random_list[rand @random_list];
  }
  
  return $random_item;
}

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

=head1 NAME

B<Fancy::Rand> selects random items from sets of lists.

=head1 SYNOPSIS

  use Fancy::Rand qw(fancy_rand fancy_rand_from_array tiny_rand instan
+t_rand);

  my $random_thing = fancy_rand($hash_of_arrays, $selected_list, { add
+itions => [@additional_items], caller => $caller });
 
  my $fancy_rand_from_array = fancy_rand_from_array(qw(red yellow gree
+n cyan blue magenta black white));

=head1 DESCRIPTION

B<Fancy::Rand> has two tools to help you select where your randomness 
+comes from: C<fancy_rand> and C<fancy_rand_from_array>.

=head2 fancy_rand

C<fancy_rand> 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 cr
+eation of other random subroutines.

  my %colors = (
    'general' => [qw(red yellow green cyan blue magenta white black gr
+ay)]
    '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) = @_;
    fancy_rand(\%colors, $selected_color_key, {  additions => $color_a
+dditions, 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<fancy_rand> by itself:

  my $random_color_one = fancy_rand(\%colors);
  my $random_color_two = fancy_rand(\%colors, undef);
  my $random_color_all = fancy_rand(\%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<fancy_rand> will return an item fro
+m the selected key.

Using C<fancy_rand> by itself:

  my $random_hair_color = fancy_rand(\%colors, 'hair');
  my $random_eyes_color = fancy_rand(\%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<fancy_rand> will return a random key.

Using C<fancy_rand> by itself:

  my $random_color_key = fancy_rand(\%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<fancy_rand> will return the list of keys f
+rom the hash to help remind you of your key options.

Using C<fancy_rand> by itself:

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

Using the newly created C<random_color>:

  my $random_color_keys = random_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<fancy_rand> will return the entire hash so
+ you can refresh your memory of what is in the hash.

Using C<fancy_rand> by itself:

  my $random_color_data = fancy_rand(\%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<fancy_rand> by itself:

  my $random_color_help = fancy_rand(\%colors, 'help');
  my $random_color_opts = fancy_rand(\%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 that you want to add to the list you have alrea
+dy 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<fancy_rand> by itself:

  my $random_hair_color = fancy_rand(\%colors, 'hair', { additions => 
+[qw(pink purple blue)] });
  my $random_eyes_color = fancy_rand(\%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<fancy_rand> by itself:

  my $random_color = fancy_rand(\%colors, 'rainboe', { caller => 'rand
+om_color' });

Using the newly created C<random_color>:

  my $random_color = random_color('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 fancy_rand_from_array

C<fancy_rand_from_array> takes an array and returns a random result. C
+<tiny_rand> and C<instant_rand> are aliases for C<fancy_rand_from_arr
+ay>.

  my $fancy_rand_from_array = fancy_rand_from_array(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 magent
+a));

=head1 AUTHOR

Lady Aleena

=cut

1;
[download]