String::Random(3pm)					User Contributed Perl Documentation				       String::Random(3pm)

NAME

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

SYNOPSIS

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

       or

	 use String::Random qw(random_regex random_string);
	 print random_regex('ddd'); # 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;
	 $pass = new String::Random;
	 print "Your password is ", $pass->randpattern("CCcc!ccn"), "
";

       This would output something like this:

	 Your password is UDwp$tj5

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

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

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

	 c	  Any lowercase character [a-z]
	 C	  Any 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:

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

       or

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

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

   Methods
       new
       new max => number
	       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 patters that don't return a fixed number of characters.

       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"]), "
";

	       would print something like this:

		 cebd

BUGS

       This is Bug Free(TM) code.  (At least until somebody finds one...)

AUTHOR

       Steven Pritchard <steve@silug.org>

SEE ALSO

       perl(1).

perl v5.10.0							    2009-06-11						       String::Random(3pm)