1String::Random(3pm) User Contributed Perl Documentation String::Random(3pm)
2
6 String::Random - Perl module to generate random strings based on a
7 pattern
8
10 version 0.32
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 or
81 my $gen = String::Random->new;
83 $gen->set_pattern(A => [ 'A'..'Z', 'a'..'z' ]);
84 The random_string function, described below, has an alternative
86 interface for adding patterns.
87 Methods
89 new
90 new max => number
91 new rand_gen => sub
92 Create a new String::Random object.
93 Optionally a parameter "max" can be included to specify the
95 maximum number of characters to return for "*" and other
96 regular expression patterns that do not return a fixed number
97 of characters.
98 Optionally a parameter "rand_gen" can be included to specify a
100 subroutine coderef for generating the random numbers used in
101 this module. The coderef must accept one argument "max" and
102 return an integer between 0 and "max - 1". The default
103 rand_gen coderef is
104 sub {
106 my ($max) = @_;
107 return int rand $max;
108 }
109 randpattern LIST
111 The randpattern method returns a random string based on the
112 concatenation of all the pattern strings in the list.
113 It will return a list of random strings corresponding to the
115 pattern strings when used in list context.
116 randregex LIST
118 The randregex method returns a random string that will match
119 the regular expression passed in the list argument.
120 Please note that the arguments to randregex are not real
122 regular expressions. Only a small subset of regular expression
123 syntax is actually supported. So far, the following regular
124 expression elements are supported:
125 \w Alphanumeric + "_".
127 \d Digits.
128 \W Printable characters other than those in \w.
129 \D Printable characters other than those in \d.
130 . Printable characters.
131 [] Character classes.
132 {} Repetition.
133 * Same as {0,}.
134 ? Same as {0,1}.
135 + Same as {1,}.
136 Regular expression support is still somewhat incomplete.
138 Currently special characters inside [] are not supported (with
139 the exception of "-" to denote ranges of characters). The
140 parser doesn't care for spaces in the "regular expression"
141 either.
142 get_pattern STRING
144 Return a pattern given a name.
145 my $gen = String::Random->new;
147 $gen->get_pattern('C');
148 (Added in version 0.32.)
150 set_pattern STRING ARRAYREF
152 Add or redefine a pattern given a name and a character set.
153 my $gen = String::Random->new;
155 $gen->set_pattern(A => [ 'A'..'Z', 'a'..'z' ]);
156 (Added in version 0.32.)
158 from_pattern
160 IGNORE! - for compatibility with an old version. DO NOT USE!
161 Functions
163 random_string PATTERN,LIST
164 random_string PATTERN
165 When called with a single scalar argument, random_string
166 returns a random string using that scalar as a pattern.
167 Optionally, references to lists containing other patterns can
168 be passed to the function. Those lists will be used for 0
169 through 9 in the pattern (meaning the maximum number of lists
170 that can be passed is 10). For example, the following code:
171 print random_string("0101",
173 ["a", "b", "c"],
174 ["d", "e", "f"]), "\n";
175 would print something like this:
177 cebd
179 random_regex REGEX_IN_STRING
181 Prints a string for the regular expression given as the string.
182 See the synposis for example.
183
185 This is Bug Free™ code. (At least until somebody finds one…)
186 Please report bugs here:
188 <https://rt.cpan.org/Public/Dist/Display.html?Name=String-Random> .
190
192 Original Author: Steven Pritchard "steve@silug.org"
193 Now maintained by: Shlomi Fish ( <http://www.shlomifish.org/> ).
195
197 This program is free software; you can redistribute it and/or modify it
198 under the same terms as Perl itself.
199
201 perl(1).
202
204 Websites
205 The following websites have more information about this module, and may
206 be of help to you. As always, in addition to those websites please use
207 your favorite search engine to discover more resources.
208 • MetaCPAN
210 A modern, open-source CPAN search engine, useful to view POD in
212 HTML format.
213 <https://metacpan.org/release/String-Random>
215 • RT: CPAN's Bug Tracker
217 The RT ( Request Tracker ) website is the default bug/issue
219 tracking system for CPAN.
220 <https://rt.cpan.org/Public/Dist/Display.html?Name=String-Random>
222 • CPANTS
224 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
226 of a distribution.
227 <http://cpants.cpanauthors.org/dist/String-Random>
229 • CPAN Testers
231 The CPAN Testers is a network of smoke testers who run automated
233 tests on uploaded CPAN distributions.
234 <http://www.cpantesters.org/distro/S/String-Random>
236 • CPAN Testers Matrix
238 The CPAN Testers Matrix is a website that provides a visual
240 overview of the test results for a distribution on various
241 Perls/platforms.
242 <http://matrix.cpantesters.org/?dist=String-Random>
244 • CPAN Testers Dependencies
246 The CPAN Testers Dependencies is a website that shows a chart of
248 the test results of all dependencies for a distribution.
249 <http://deps.cpantesters.org/?module=String::Random>
251 Bugs / Feature Requests
253 Please report any bugs or feature requests by email to
254 "bug-string-random at rt.cpan.org", or through the web interface at
255 <https://rt.cpan.org/Public/Bug/Report.html?Queue=String-Random>. You
256 will be automatically notified of any progress on the request by the
257 system.
258 Source Code
260 The code is open to the world, and available for you to hack on. Please
261 feel free to browse it and play with it, or whatever. If you want to
262 contribute patches, please send me a diff or prod me to pull from your
263 repository :)
264 <https://github.com/shlomif/string-random>
266 git clone http://github.com/shlomif/String-Random
268
270 Shlomi Fish <shlomif@cpan.org>
271
273 Please report any bugs or feature requests on the bugtracker website
274 <https://github.com/shlomif/string-random/issues>
275 When submitting a bug or request, please include a test-file or a patch
277 to an existing test-file that illustrates the bug or desired feature.
278
280 This software is copyright (c) 2021 by Shlomi Fish.
281 This is free software; you can redistribute it and/or modify it under
283 the same terms as the Perl 5 programming language system itself.
284perl v5.38.0 2023-07-21 String::Random(3pm)