1String::Random(3pm)   User Contributed Perl Documentation  String::Random(3pm)
2
3
4

NAME

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

VERSION

10       version 0.32
11

SYNOPSIS

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
19       or
20
21           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

DESCRIPTION

26       This module makes it trivial to generate random strings.
27
28       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
32           use String::Random;
33           my $pass = String::Random->new;
34           print "Your password is ", $pass->randpattern("CCcc!ccn"), "\n";
35
36       This would output something like this:
37
38         Your password is UDwp$tj5
39
40       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
47       If you are more comfortable dealing with regular expressions, the
48       following code would have a similar result:
49
50         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
55   Patterns
56       The pre-defined patterns (for use with randpattern() and
57       random_pattern()) are as follows:
58
59         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
67       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
72         my $gen = String::Random->new;
73         $gen->{'A'} = [ 'A'..'Z', 'a'..'z' ];
74
75       or
76
77         my $gen = String::Random->new;
78         $gen->{'A'} = [ @{$gen->{'C'}}, @{$gen->{'c'}} ];
79
80       or
81
82         my $gen = String::Random->new;
83         $gen->set_pattern(A => [ 'A'..'Z', 'a'..'z' ]);
84
85       The random_string function, described below, has an alternative
86       interface for adding patterns.
87
88   Methods
89       new
90       new max => number
91       new rand_gen => sub
92               Create a new String::Random object.
93
94               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
99               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
105                sub {
106                    my ($max) = @_;
107                    return int rand $max;
108                }
109
110       randpattern LIST
111               The randpattern method returns a random string based on the
112               concatenation of all the pattern strings in the list.
113
114               It will return a list of random strings corresponding to the
115               pattern strings when used in list context.
116
117       randregex LIST
118               The randregex method returns a random string that will match
119               the regular expression passed in the list argument.
120
121               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
126                 \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
137               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
143       get_pattern STRING
144               Return a pattern given a name.
145
146                 my $gen = String::Random->new;
147                 $gen->get_pattern('C');
148
149               (Added in version 0.32.)
150
151       set_pattern STRING ARRAYREF
152               Add or redefine a pattern given a name and a character set.
153
154                 my $gen = String::Random->new;
155                 $gen->set_pattern(A => [ 'A'..'Z', 'a'..'z' ]);
156
157               (Added in version 0.32.)
158
159       from_pattern
160               IGNORE! - for compatibility with an old version. DO NOT USE!
161
162   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
172                   print random_string("0101",
173                                       ["a", "b", "c"],
174                                       ["d", "e", "f"]), "\n";
175
176               would print something like this:
177
178                   cebd
179
180       random_regex REGEX_IN_STRING
181               Prints a string for the regular expression given as the string.
182               See the synposis for example.
183

BUGS

185       This is Bug Free™ code.  (At least until somebody finds one…)
186
187       Please report bugs here:
188
189       <https://rt.cpan.org/Public/Dist/Display.html?Name=String-Random> .
190

AUTHOR

192       Original Author: Steven Pritchard "steve@silug.org"
193
194       Now maintained by: Shlomi Fish ( <http://www.shlomifish.org/> ).
195

LICENSE

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

SEE ALSO

201       perl(1).
202

SUPPORT

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
209       •   MetaCPAN
210
211           A modern, open-source CPAN search engine, useful to view POD in
212           HTML format.
213
214           <https://metacpan.org/release/String-Random>
215
216       •   RT: CPAN's Bug Tracker
217
218           The RT ( Request Tracker ) website is the default bug/issue
219           tracking system for CPAN.
220
221           <https://rt.cpan.org/Public/Dist/Display.html?Name=String-Random>
222
223       •   CPANTS
224
225           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
226           of a distribution.
227
228           <http://cpants.cpanauthors.org/dist/String-Random>
229
230       •   CPAN Testers
231
232           The CPAN Testers is a network of smoke testers who run automated
233           tests on uploaded CPAN distributions.
234
235           <http://www.cpantesters.org/distro/S/String-Random>
236
237       •   CPAN Testers Matrix
238
239           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
243           <http://matrix.cpantesters.org/?dist=String-Random>
244
245       •   CPAN Testers Dependencies
246
247           The CPAN Testers Dependencies is a website that shows a chart of
248           the test results of all dependencies for a distribution.
249
250           <http://deps.cpantesters.org/?module=String::Random>
251
252   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
259   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
265       <https://github.com/shlomif/string-random>
266
267         git clone http://github.com/shlomif/String-Random
268

AUTHOR

270       Shlomi Fish <shlomif@cpan.org>
271

BUGS

273       Please report any bugs or feature requests on the bugtracker website
274       <https://github.com/shlomif/string-random/issues>
275
276       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
282       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.
284
285
286
287perl v5.38.0                      2023-07-21               String::Random(3pm)
Impressum