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

NAME

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

VERSION

10       version 0.31
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       The random_string function, described below, has an alternative
81       interface for adding patterns.
82
83   Methods
84       new
85       new max => number
86       new rand_gen => sub
87               Create a new String::Random object.
88
89               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
94               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
100                sub {
101                    my ($max) = @_;
102                    return int rand $max;
103                }
104
105       randpattern LIST
106               The randpattern method returns a random string based on the
107               concatenation of all the pattern strings in the list.
108
109               It will return a list of random strings corresponding to the
110               pattern strings when used in list context.
111
112       randregex LIST
113               The randregex method returns a random string that will match
114               the regular expression passed in the list argument.
115
116               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
121                 \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
132               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
138       from_pattern
139               IGNORE! - for compatibility with an old version. DO NOT USE!
140
141   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
151                   print random_string("0101",
152                                       ["a", "b", "c"],
153                                       ["d", "e", "f"]), "\n";
154
155               would print something like this:
156
157                   cebd
158
159       random_regex REGEX_IN_STRING
160               Prints a string for the regular expression given as the string.
161               See the synposis for example.
162

BUGS

164       This is Bug FreeX code.  (At least until somebody finds oneX)
165
166       Please report bugs here:
167
168       <https://rt.cpan.org/Public/Dist/Display.html?Name=String-Random> .
169

AUTHOR

171       Original Author: Steven Pritchard "steve@silug.org"
172
173       Now maintained by: Shlomi Fish ( <http://www.shlomifish.org/> ).
174

LICENSE

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

SEE ALSO

180       perl(1).
181

SUPPORT

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
188       •   MetaCPAN
189
190           A modern, open-source CPAN search engine, useful to view POD in
191           HTML format.
192
193           <https://metacpan.org/release/String-Random>
194
195       •   RT: CPAN's Bug Tracker
196
197           The RT ( Request Tracker ) website is the default bug/issue
198           tracking system for CPAN.
199
200           <https://rt.cpan.org/Public/Dist/Display.html?Name=String-Random>
201
202       •   CPANTS
203
204           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
205           of a distribution.
206
207           <http://cpants.cpanauthors.org/dist/String-Random>
208
209       •   CPAN Testers
210
211           The CPAN Testers is a network of smoke testers who run automated
212           tests on uploaded CPAN distributions.
213
214           <http://www.cpantesters.org/distro/S/String-Random>
215
216       •   CPAN Testers Matrix
217
218           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
222           <http://matrix.cpantesters.org/?dist=String-Random>
223
224       •   CPAN Testers Dependencies
225
226           The CPAN Testers Dependencies is a website that shows a chart of
227           the test results of all dependencies for a distribution.
228
229           <http://deps.cpantesters.org/?module=String::Random>
230
231   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
238   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
244       <https://github.com/shlomif/string-random>
245
246         git clone http://github.com/shlomif/String-Random
247

AUTHOR

249       Shlomi Fish <shlomif@cpan.org>
250

BUGS

252       Please report any bugs or feature requests on the bugtracker website
253       <https://github.com/shlomif/string-random/issues>
254
255       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
261       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.
263
264
265
266perl v5.34.0                      2021-07-22                 String::Random(3)
Impressum