1String::Random(3) User Contributed Perl Documentation String::Random(3)
2
6 String::Random - Perl module to generate random strings based on a
7 pattern
8
10 version 0.31
11
13 use String::Random;
14 my $string_gen = String::Random->new;
15 print $string_gen->randregex('\d\d\d'); # Prints 3 random digits
16 # Prints 3 random printable characters
17 print $string_gen->randpattern("...");
18 or
20 use String::Random qw(random_regex random_string);
22 print random_regex('\d\d\d'); # Also prints 3 random digits
23 print random_string("..."); # Also prints 3 random printable characters
24
26 This module makes it trivial to generate random strings.
27 As an example, let's say you are writing a script that needs to
29 generate a random password for a user. The relevant code might look
30 something like this:
31 use String::Random;
33 my $pass = String::Random->new;
34 print "Your password is ", $pass->randpattern("CCcc!ccn"), "\n";
35 This would output something like this:
37 Your password is UDwp$tj5
39 NOTE!!!: currently, "String::Random" defaults to Perl's built-in
41 predictable random number generator so the passwords generated by it
42 are insecure. See the "rand_gen" option to "String::Random"
43 constructor to specify a more secure random number generator. There is
44 no equivalent to this in the procedural interface, you must use the
45 object-oriented interface to get this functionality.
46 If you are more comfortable dealing with regular expressions, the
48 following code would have a similar result:
49 use String::Random;
51 my $pass = String::Random->new;
52 print "Your password is ",
53 $pass->randregex('[A-Z]{2}[a-z]{2}.[a-z]{2}\d'), "\n";
54 Patterns
56 The pre-defined patterns (for use with "randpattern()" and
57 "random_pattern()") are as follows:
58 c Any Latin lowercase character [a-z]
60 C Any Latin uppercase character [A-Z]
61 n Any digit [0-9]
62 ! A punctuation character [~`!@$%^&*()-_+={}[]|\:;"'.<>?/#,]
63 . Any of the above
64 s A "salt" character [A-Za-z0-9./]
65 b Any binary data
66 These can be modified, but if you need a different pattern it is better
68 to create another pattern, possibly using one of the pre-defined as a
69 base. For example, if you wanted a pattern "A" that contained all
70 upper and lower case letters ("[A-Za-z]"), the following would work:
71 my $gen = String::Random->new;
73 $gen->{'A'} = [ 'A'..'Z', 'a'..'z' ];
74 or
76 my $gen = String::Random->new;
78 $gen->{'A'} = [ @{$gen->{'C'}}, @{$gen->{'c'}} ];
79 The random_string function, described below, has an alternative
81 interface for adding patterns.
82 Methods
84 new
85 new max => number
86 new rand_gen => sub
87 Create a new String::Random object.
88 Optionally a parameter "max" can be included to specify the
90 maximum number of characters to return for "*" and other
91 regular expression patterns that do not return a fixed number
92 of characters.
93 Optionally a parameter "rand_gen" can be included to specify a
95 subroutine coderef for generating the random numbers used in
96 this module. The coderef must accept one argument "max" and
97 return an integer between 0 and "max - 1". The default
98 rand_gen coderef is
99 sub {
101 my ($max) = @_;
102 return int rand $max;
103 }
104 randpattern LIST
106 The randpattern method returns a random string based on the
107 concatenation of all the pattern strings in the list.
108 It will return a list of random strings corresponding to the
110 pattern strings when used in list context.
111 randregex LIST
113 The randregex method returns a random string that will match
114 the regular expression passed in the list argument.
115 Please note that the arguments to randregex are not real
117 regular expressions. Only a small subset of regular expression
118 syntax is actually supported. So far, the following regular
119 expression elements are supported:
120 \w Alphanumeric + "_".
122 \d Digits.
123 \W Printable characters other than those in \w.
124 \D Printable characters other than those in \d.
125 . Printable characters.
126 [] Character classes.
127 {} Repetition.
128 * Same as {0,}.
129 ? Same as {0,1}.
130 + Same as {1,}.
131 Regular expression support is still somewhat incomplete.
133 Currently special characters inside [] are not supported (with
134 the exception of "-" to denote ranges of characters). The
135 parser doesn't care for spaces in the "regular expression"
136 either.
137 from_pattern
139 IGNORE! - for compatibility with an old version. DO NOT USE!
140 Functions
142 random_string PATTERN,LIST
143 random_string PATTERN
144 When called with a single scalar argument, random_string
145 returns a random string using that scalar as a pattern.
146 Optionally, references to lists containing other patterns can
147 be passed to the function. Those lists will be used for 0
148 through 9 in the pattern (meaning the maximum number of lists
149 that can be passed is 10). For example, the following code:
150 print random_string("0101",
152 ["a", "b", "c"],
153 ["d", "e", "f"]), "\n";
154 would print something like this:
156 cebd
158 random_regex REGEX_IN_STRING
160 Prints a string for the regular expression given as the string.
161 See the synposis for example.
162
164 This is Bug FreeX code. (At least until somebody finds oneX)
165 Please report bugs here:
167 <https://rt.cpan.org/Public/Dist/Display.html?Name=String-Random> .
169
171 Original Author: Steven Pritchard "steve@silug.org"
172 Now maintained by: Shlomi Fish ( <http://www.shlomifish.org/> ).
174
176 This program is free software; you can redistribute it and/or modify it
177 under the same terms as Perl itself.
178
180 perl(1).
181
183 Websites
184 The following websites have more information about this module, and may
185 be of help to you. As always, in addition to those websites please use
186 your favorite search engine to discover more resources.
187 • MetaCPAN
189 A modern, open-source CPAN search engine, useful to view POD in
191 HTML format.
192 <https://metacpan.org/release/String-Random>
194 • RT: CPAN's Bug Tracker
196 The RT ( Request Tracker ) website is the default bug/issue
198 tracking system for CPAN.
199 <https://rt.cpan.org/Public/Dist/Display.html?Name=String-Random>
201 • CPANTS
203 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
205 of a distribution.
206 <http://cpants.cpanauthors.org/dist/String-Random>
208 • CPAN Testers
210 The CPAN Testers is a network of smoke testers who run automated
212 tests on uploaded CPAN distributions.
213 <http://www.cpantesters.org/distro/S/String-Random>
215 • CPAN Testers Matrix
217 The CPAN Testers Matrix is a website that provides a visual
219 overview of the test results for a distribution on various
220 Perls/platforms.
221 <http://matrix.cpantesters.org/?dist=String-Random>
223 • CPAN Testers Dependencies
225 The CPAN Testers Dependencies is a website that shows a chart of
227 the test results of all dependencies for a distribution.
228 <http://deps.cpantesters.org/?module=String::Random>
230 Bugs / Feature Requests
232 Please report any bugs or feature requests by email to
233 "bug-string-random at rt.cpan.org", or through the web interface at
234 <https://rt.cpan.org/Public/Bug/Report.html?Queue=String-Random>. You
235 will be automatically notified of any progress on the request by the
236 system.
237 Source Code
239 The code is open to the world, and available for you to hack on. Please
240 feel free to browse it and play with it, or whatever. If you want to
241 contribute patches, please send me a diff or prod me to pull from your
242 repository :)
243 <https://github.com/shlomif/string-random>
245 git clone http://github.com/shlomif/String-Random
247
249 Shlomi Fish <shlomif@cpan.org>
250
252 Please report any bugs or feature requests on the bugtracker website
253 <https://github.com/shlomif/string-random/issues>
254 When submitting a bug or request, please include a test-file or a patch
256 to an existing test-file that illustrates the bug or desired feature.
257
259 This software is copyright (c) 2020 by Shlomi Fish.
260 This is free software; you can redistribute it and/or modify it under
262 the same terms as the Perl 5 programming language system itself.
263perl v5.34.0 2021-07-22 String::Random(3)