NAME

       String::Random - Perl module to generate random strings based on a pattern

SYNOPSIS

           use String::Random;
           my $string_gen = String::Random->new;
           print $string_gen->randregex('\d\d\d'); # Prints 3 random digits
           # Prints 3 random printable characters
           print $string_gen->randpattern("...");

       or

           use String::Random qw(random_regex random_string);
           print random_regex('\d\d\d'); # Also prints 3 random digits
           print random_string("...");   # Also prints 3 random printable characters

DESCRIPTION

       This module makes it trivial to generate random strings.

       As an example, let's say you are writing a script that needs to generate a random password
       for a user.  The relevant code might look something like this:

           use String::Random;
           my $pass = String::Random->new;
           print "Your password is ", $pass->randpattern("CCcc!ccn"), "\n";

       This would output something like this:

         Your password is UDwp$tj5

       NOTE!!!: currently, String::Random uses Perl's built-in predictable random number
       generator so the passwords generated by it are insecure.

       If you are more comfortable dealing with regular expressions, the following code would
       have a similar result:

         use String::Random;
         my $pass = String::Random->new;
         print "Your password is ",
             $pass->randregex('[A-Z]{2}[a-z]{2}.[a-z]{2}\d'), "\n";

   Patterns
       The pre-defined patterns (for use with "randpattern()" and "random_pattern()") are as
       follows:

         c        Any Latin lowercase character [a-z]
         C        Any Latin uppercase character [A-Z]
         n        Any digit [0-9]
         !        A punctuation character [~`!@$%^&*()-_+={}[]|\:;"'.<>?/#,]
         .        Any of the above
         s        A "salt" character [A-Za-z0-9./]
         b        Any binary data

       These can be modified, but if you need a different pattern it is better to create another
       pattern, possibly using one of the pre-defined as a base.  For example, if you wanted a
       pattern "A" that contained all upper and lower case letters ("[A-Za-z]"), the following
       would work:

         my $gen = String::Random->new;
         $gen->{'A'} = [ 'A'..'Z', 'a'..'z' ];

       or

         my $gen = String::Random->new;
         $gen->{'A'} = [ @{$gen->{'C'}}, @{$gen->{'c'}} ];

       The random_string function, described below, has an alternative interface for adding
       patterns.

   Methods
       new
       new max => number
       new rand_gen => sub
               Create a new String::Random object.

               Optionally a parameter "max" can be included to specify the maximum number of
               characters to return for "*" and other regular expression patterns that do not
               return a fixed number of characters.

               Optionally a parameter "rand_gen" can be included to specify a subroutine coderef
               for generating the random numbers used in this module. The coderef must accept one
               argument "max" and return an integer between 0 and "max - 1".  The default
               rand_gen coderef is

                sub {
                    my ($max) = @_;
                    return int rand $max;
                }

       randpattern LIST
               The randpattern method returns a random string based on the concatenation of all
               the pattern strings in the list.

               It will return a list of random strings corresponding to the pattern strings when
               used in list context.

       randregex LIST
               The randregex method returns a random string that will match the regular
               expression passed in the list argument.

               Please note that the arguments to randregex are not real regular expressions.
               Only a small subset of regular expression syntax is actually supported.  So far,
               the following regular expression elements are supported:

                 \w    Alphanumeric + "_".
                 \d    Digits.
                 \W    Printable characters other than those in \w.
                 \D    Printable characters other than those in \d.
                 .     Printable characters.
                 []    Character classes.
                 {}    Repetition.
                 *     Same as {0,}.
                 ?     Same as {0,1}.
                 +     Same as {1,}.

               Regular expression support is still somewhat incomplete.  Currently special
               characters inside [] are not supported (with the exception of "-" to denote ranges
               of characters).  The parser doesn't care for spaces in the "regular expression"
               either.

   Functions
       random_string PATTERN,LIST
       random_string PATTERN
               When called with a single scalar argument, random_string returns a random string
               using that scalar as a pattern.  Optionally, references to lists containing other
               patterns can be passed to the function.  Those lists will be used for 0 through 9
               in the pattern (meaning the maximum number of lists that can be passed is 10).
               For example, the following code:

                   print random_string("0101",
                                       ["a", "b", "c"],
                                       ["d", "e", "f"]), "\n";

               would print something like this:

                   cebd

BUGS

       This is Bug FreeX code.  (At least until somebody finds oneX)

       Please report bugs here:

       <https://rt.cpan.org/Public/Dist/Display.html?Name=String-Random> .

AUTHOR

       Original Author: Steven Pritchard "steve@silug.org"

       Now maintained by: Shlomi Fish ( <http://www.shlomifish.org/> ).

LICENSE

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

SEE ALSO

       perl(1).