Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl-Sensitive Sunglasses

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

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

In reply to RFC: Proofread POD for my main random module, please? (more) by Lady_Aleena

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?

    What's my password?
    Create A New User
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others romping around the Monastery: (5)
    As of 2020-12-04 09:03 GMT
    Find Nodes?
      Voting Booth?
      How often do you use taint mode?

      Results (58 votes). Check out past polls.