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.30
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

VERSION

164       version 0.30
165

BUGS

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

AUTHOR

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

LICENSE

179       This program is free software; you can redistribute it and/or modify it
180       under the same terms as Perl itself.
181

SEE ALSO

183       perl(1).
184

AUTHOR

186       Shlomi Fish <shlomif@cpan.org>
187
189       This software is copyright (c) 2018 by Shlomi Fish.
190
191       This is free software; you can redistribute it and/or modify it under
192       the same terms as the Perl 5 programming language system itself.
193

BUGS

195       Please report any bugs or feature requests on the bugtracker website
196       <https://github.com/shlomif/string-random/issues>
197
198       When submitting a bug or request, please include a test-file or a patch
199       to an existing test-file that illustrates the bug or desired feature.
200

SUPPORT

202   Perldoc
203       You can find documentation for this module with the perldoc command.
204
205         perldoc String::Random
206
207   Websites
208       The following websites have more information about this module, and may
209       be of help to you. As always, in addition to those websites please use
210       your favorite search engine to discover more resources.
211
212       ·   MetaCPAN
213
214           A modern, open-source CPAN search engine, useful to view POD in
215           HTML format.
216
217           <https://metacpan.org/release/String-Random>
218
219       ·   Search CPAN
220
221           The default CPAN search engine, useful to view POD in HTML format.
222
223           <http://search.cpan.org/dist/String-Random>
224
225       ·   RT: CPAN's Bug Tracker
226
227           The RT ( Request Tracker ) website is the default bug/issue
228           tracking system for CPAN.
229
230           <https://rt.cpan.org/Public/Dist/Display.html?Name=String-Random>
231
232       ·   AnnoCPAN
233
234           The AnnoCPAN is a website that allows community annotations of Perl
235           module documentation.
236
237           <http://annocpan.org/dist/String-Random>
238
239       ·   CPAN Ratings
240
241           The CPAN Ratings is a website that allows community ratings and
242           reviews of Perl modules.
243
244           <http://cpanratings.perl.org/d/String-Random>
245
246       ·   CPANTS
247
248           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
249           of a distribution.
250
251           <http://cpants.cpanauthors.org/dist/String-Random>
252
253       ·   CPAN Testers
254
255           The CPAN Testers is a network of smoke testers who run automated
256           tests on uploaded CPAN distributions.
257
258           <http://www.cpantesters.org/distro/S/String-Random>
259
260       ·   CPAN Testers Matrix
261
262           The CPAN Testers Matrix is a website that provides a visual
263           overview of the test results for a distribution on various
264           Perls/platforms.
265
266           <http://matrix.cpantesters.org/?dist=String-Random>
267
268       ·   CPAN Testers Dependencies
269
270           The CPAN Testers Dependencies is a website that shows a chart of
271           the test results of all dependencies for a distribution.
272
273           <http://deps.cpantesters.org/?module=String::Random>
274
275   Bugs / Feature Requests
276       Please report any bugs or feature requests by email to
277       "bug-string-random at rt.cpan.org", or through the web interface at
278       <https://rt.cpan.org/Public/Bug/Report.html?Queue=String-Random>. You
279       will be automatically notified of any progress on the request by the
280       system.
281
282   Source Code
283       The code is open to the world, and available for you to hack on. Please
284       feel free to browse it and play with it, or whatever. If you want to
285       contribute patches, please send me a diff or prod me to pull from your
286       repository :)
287
288       <https://github.com/shlomif/string-random>
289
290         git clone http://github.com/shlomif/String-Random
291
292
293
294perl v5.28.1                      2019-02-02                 String::Random(3)
Impressum