.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Data::Random 3" .TH Data::Random 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Data::Random \- Perl module to generate random data .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use Data::Random qw(:all); \& \& my @random_words = rand_words( size => 10 ); \& \& my @random_chars = rand_chars( set => \*(Aqall\*(Aq, min => 5, max => 8 ); \& my $string = rand_chars( set => \*(Aqall\*(Aq, min => 5, max => 8 ); \& \& my @random_set = rand_set( set => \e@set, size => 5 ); \& \& my $random_enum = rand_enum( set => \e@set ); \& my $random_enum = rand_enum( \e@set ); # shortcut \& \& my $random_date = rand_date(); \& \& my $random_time = rand_time(); \& \& my $random_datetime = rand_datetime(); \& \& open(my $file, ">", "rand_image.png") or die $!; \& binmode($file); \& print $file rand_image( bgcolor => [0, 0, 0] ); \& close($file); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" A module used to generate random data. Useful mostly for test programs. .SH METHODS .IX Header "METHODS" .SS \fBrand_words()\fP .IX Subsection "rand_words()" This returns a list of random words given a wordlist. See below for possible parameters. .IP \(bu 4 wordlist \- the path to the wordlist file. A lot of systems have one at /usr/dict/words. You can also optionally supply a Data::Random::WordList object to keep a persistent wordlist. The default is the wordlist distributed with this module. .IP \(bu 4 min \- the minimum number of words to return. The default is 1. .IP \(bu 4 max \- the maximum number of words to return. The default is 1. .IP \(bu 4 size \- the number of words to return. The default is 1. If you supply a value for 'size', then 'min' and 'max' aren't paid attention to. .IP \(bu 4 shuffle \- whether or not the words should be randomly shuffled. Set this to 0 if you don't want the words shuffled. The default is 1. Random::Data::WordList returns words in the order that they're viewed in the word list file, so shuffling will make sure that the results are a little more random. .SS \fBrand_chars()\fP .IX Subsection "rand_chars()" When called in a list context this returns a list of random characters given a set of characters. In a scalar context it returns a string of random characters. See below for possible parameters. .IP \(bu 4 set \- the set of characters to be used. This value can be either a reference to an array of strings, or one of the following: .Sp .Vb 8 \& alpha \- alphabetic characters: a\-z, A\-Z \& upperalpha \- upper case alphabetic characters: A\-Z \& loweralpha \- lower case alphabetic characters: a\-z \& numeric \- numeric characters: 0\-9 \& alphanumeric \- alphanumeric characters: a\-z, A\-Z, 0\-9 \& char \- non\-alphanumeric characters: # ~ ! @ $ % ^ & * ( ) _ + = \- { } | : " < > ? / . \*(Aq ; ] [ \e \` \& misc \- same as \*(Aqchar\*(Aq \& all \- all of the above .Ve .IP \(bu 4 min \- the minimum number of characters to return. The default is 0. .IP \(bu 4 max \- the maximum number of characters to return. The default is the size of the set. .IP \(bu 4 size \- the number of characters to return. The default is 1. If you supply a value for 'size', then 'min' and 'max' aren't paid attention to. .IP \(bu 4 shuffle \- whether or not the characters should be randomly shuffled. Set this to 0 if you want the characters to stay in the order received. The default is 1. .SS \fBrand_set()\fP .IX Subsection "rand_set()" This returns a random set of elements given an initial set. See below for possible parameters. .IP \(bu 4 set \- the set of strings to be used. This should be a reference to an array of strings. .IP \(bu 4 min \- the minimum number of strings to return. The default is 0. .IP \(bu 4 max \- the maximum number of strings to return. The default is the size of the set. .IP \(bu 4 size \- the number of strings to return. The default is 1. If you supply a value for 'size', then 'min' and 'max' aren't paid attention to. .IP \(bu 4 shuffle \- whether or not the strings should be randomly shuffled. Set this to 0 if you want the strings to stay in the order received. The default is 1. .SS \fBrand_enum()\fP .IX Subsection "rand_enum()" This returns a random element given an initial set. See below for possible parameters. .IP \(bu 4 set \- the set of strings to be used. This should be a reference to an array of strings. The \f(CW\*(C`set\*(C'\fR key will be assumed if the array reference is passed as the only argument. .SS \fBrand_date()\fP .IX Subsection "rand_date()" This returns a random date in the form "YYYY-MM-DD". 2\-digit years are not currently supported. Efforts are made to make sure you're returned a truly valid date\-\-ie, you'll never be returned the date February 31st. See the options below to find out how to control the date range. Here are a few examples: .PP .Vb 2 \& # returns a date somewhere in between the current date, and one year from the current date \& $date = rand_date(); \& \& # returns a date somewhere in between September 21, 1978 and September 21, 1979 \& $date = rand_date( min => \*(Aq1978\-9\-21\*(Aq ); \& \& # returns a date somewhere in between September 21, 1978 and the current date \& $date = rand_date( min => \*(Aq1978\-9\-21\*(Aq, max => \*(Aqnow\*(Aq ); \& \& # returns a date somewhere in between the current date and September 21, 2008 \& $date = rand_date( min => \*(Aqnow\*(Aq, max => \*(Aq2008\-9\-21\*(Aq ); .Ve .PP See below for possible parameters. .IP \(bu 4 min \- the minimum date to be returned. It should be in the form "YYYY-MM-DD" or you can alternatively use the string "now" to represent the current date. The default is the current date; .IP \(bu 4 max \- the maximum date to be returned. It should be in the form "YYYY-MM-DD" or you can alternatively use the string "now" to represent the current date. The default is one year from the minimum date; .SS \fBrand_time()\fP .IX Subsection "rand_time()" This returns a random time in the form "HH:MM:SS". 24 hour times are supported. See the options below to find out how to control the time range. Here are a few examples: .PP .Vb 2 \& # returns a random 24\-hr time (between 00:00:00 and 23:59:59) \& $time = rand_time(); \& \& # returns a time somewhere in between 04:00:00 and the end of the day \& $time = rand_time( min => \*(Aq4:0:0\*(Aq ); \& \& # returns a time somewhere in between 8:00:00 and the current time (if it\*(Aqs after 8:00) \& $time = rand_time( min => \*(Aq12:00:00\*(Aq, max => \*(Aqnow\*(Aq ); \& \& # returns a date somewhere in between the current time and the end of the day \& $time = rand_time( min => \*(Aqnow\*(Aq ); .Ve .PP See below for possible parameters. .IP \(bu 4 min \- the minimum time to be returned. It should be in the form "HH:MM:SS" or you can alternatively use the string "now" to represent the current time. The default is 00:00:00; .IP \(bu 4 max \- the maximum time to be returned. It should be in the form "HH:MM:SS" or you can alternatively use the string "now" to represent the current time. The default is 23:59:59; .SS \fBrand_datetime()\fP .IX Subsection "rand_datetime()" This returns a random date and time in the form "YYYY-MM-DD HH:MM:SS". See the options below to find out how to control the date/time range. Here are a few examples: .PP .Vb 2 \& # returns a date somewhere in between the current date/time, and one year from the current date/time \& $datetime = rand_datetime(); \& \& # returns a date somewhere in between 4:00 September 21, 1978 and 4:00 September 21, 1979 \& $datetime = rand_datetime( min => \*(Aq1978\-9\-21 4:0:0\*(Aq ); \& \& # returns a date somewhere in between 4:00 September 21, 1978 and the current date \& $datetime = rand_datetime( min => \*(Aq1978\-9\-21 4:0:0\*(Aq, max => \*(Aqnow\*(Aq ); \& \& # returns a date somewhere in between the current date/time and the end of the day September 21, 2008 \& $datetime = rand_datetime( min => \*(Aqnow\*(Aq, max => \*(Aq2008\-9\-21 23:59:59\*(Aq ); .Ve .PP See below for possible parameters. .IP \(bu 4 min \- the minimum date/time to be returned. It should be in the form "YYYY-MM-DD HH:MM:SS" or you can alternatively use the string "now" to represent the current date/time. The default is the current date/time; .IP \(bu 4 max \- the maximum date/time to be returned. It should be in the form "YYYY-MM-DD HH:MM:SS" or you can alternatively use the string "now" to represent the current date/time. The default is one year from the minimum date/time; .SS \fBrand_image()\fP .IX Subsection "rand_image()" This returns a random image. Currently only PNG images are supported. See below for possible parameters. .IP \(bu 4 minwidth \- the minimum width of the image. The default is 1. .IP \(bu 4 maxwidth \- the maximum width of the image. The default is 100. .IP \(bu 4 width \- the width of the image. If you supply a value for 'width', then 'minwidth' and 'maxwidth' aren't paid attention to. .IP \(bu 4 minheight \- the minimum height of the image. The default is 1. .IP \(bu 4 maxheight \- the maximum height of the image. The default is 100. .IP \(bu 4 height \- the height of the image. If you supply a value for 'width', then 'minwidth' and 'maxwidth' aren't paid attention to. .IP \(bu 4 minpixels \- the minimum number of random pixels to display on the image. The default is 0. .IP \(bu 4 maxpixels \- the maximum number of random pixels to display on the image. The default is width * height. .IP \(bu 4 pixels \- the number of random pixels to display on the image. If you supply a value for 'pixels', then 'minpixels' and 'maxpixels' aren't paid attention to. .IP \(bu 4 bgcolor \- the background color of the image. The value must be a reference to an RGB array where each element is an integer between 0 and 255 (eg. [ 55, 120, 255 ]). .IP \(bu 4 fgcolor \- the foreground color of the image. The value must be a reference to an RGB array where each element is an integer between 0 and 255 (eg. [ 55, 120, 255 ]). .SH VERSION .IX Header "VERSION" 0.12 .SH AUTHOR .IX Header "AUTHOR" Originally written by: Adekunle Olonoh .PP Currently maintained by: Buddy Burden (barefoot@cpan.org), starting with version 0.06 .SH CREDITS .IX Header "CREDITS" .Vb 3 \& Hiroki Chalfant \& David Sarno \& Michiel Beijen .Ve .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright (c) 2000\-2011 Adekunle Olonoh. Copyright (c) 2011\-2015 Buddy Burden. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Data::Random::WordList