File::Random - Perl module for random selecting of a file
use File::Random qw/random_file/; my $fname = random_file(); my $fname2 = random_file(-dir => $dir); my $random_gif = random_file(-dir => $dir, -check => qr/\.gif$/, -recursive => 1); my $no_exe = random_file(-dir => $dir, -check => sub {! -x}); my @jokes_of_the_day = content_of_random_file(-dir => '/usr/lib/jokes'); my $joke_of_the_day = content_of_random_file(-dir => '/usr/lib/jokes'); my $word_of_the_day = random_line('/usr/share/dict/words');
This module simplifies the routine job of selecting a random file. (As you can find at CGI scripts).
It's done, because it's boring (and errorprone), always to write something like
my @files = (<*.*>); my $randf = $files[rand @files];
or
opendir DIR, " ... " or die " ... "; my @files = grep {-f ...} (readdir DIR); closedir DIR; my $randf = $files[rand @files];
It also becomes very boring and very dangerous to write randomly selection for subdirectory searching with special check-routines.
The simple standard job of selecting a random line from a file is implemented, too.
Returns a randomly selected file(name) from the specified directory If the directory is empty, undef will be returned. There 3 options:
my $file = random_file( -dir => $dir, -check => qr/.../, # or sub { .... } -recursive => 1 # or 0 );
Specifies the directory where file has to come from.
Is the -dir option missing, a random file from the current directory will be used. That means '.' is the default for the -dir option.
With the -check option you can either define a regex every filename has to follow, or a sub routine which gets the filename as argument. The filename includes the relative path (from the -dir directory or the current directory).
Note, that -check doesn't accept anything else than a regexp or a subroutine. A string like '/.../' won't work. I still work on that.
The default is no checking (undef).
Enables, that subdirectories are scanned for files, too. Every file, independent from its position in the file tree, has the same chance to be choosen. Now the relative path from the given subdirectory or the current directory of the randomly choosen file is included to the file name.
Every true value sets recursive behaviour on, every false value switches off. The default if false (undef).
Note, that I programmed the recursive routine very defendly (using File::Find). So switching -recursive on, slowers the program a bit :-)
Gives a warning. Unknown options are ignored. Note, that upper/lower case makes a difference. (Maybe, once a day I'll change it)
Returns the content of a randomly selected random file. In list context it returns an array of the lines of the selected file, in scalar context it returns a multiline string with whole the file. The lines aren't chomped.
This function has the same parameter and a similar behaviour to the random_file method. Note, that -check still gets the filename and not the filecontent.
Returns a random_line from a (existing) file.
If the file is empty, undef is returned.
None by default.
You can export the function random_file with use File::Random qw/random_file/;, use File::Random qw/content_of_random_file/ or with the more simple use File::Random qw/:all/;.
use File::Random qw/random_file/;
use File::Random qw/content_of_random_file/
use File::Random qw/:all/;
I didn't want to pollute namespaces as I could imagine, users write methods random_file to create a file with random content. If you think I'm paranoid, please tell me, then I'll take it into the export.
This module requires these other modules and libraries:
Test::More Test::Exception Test::Class Set::Scalar File::Temp
Test::Class itselfs needs the following additional modules: Attribute::Handlers Class::ISA IO::File Storable Test::Builder Test::Builder::Tester Test::Differences
All these modules are needed only for the tests. You can work with the module even without them. These modules are only needed for my test routines, not by the File::Random itself. (However, it's a good idea most to install most of the modules anyway).
The -check option doesn't except a string looking like a regexp. In future versions there should be the possibility of passing a string like '/..../' instead of the regexp qr/.../';
A -firstline or -lines = [1 .. 10]> option for the content_of_random_file could be useful. Later something like -randomline option should be implemented, too. (Making the same as random_line( random_file( ... ) )) content_of_random_file is very long, perhaps I'll implement a synonym corf.
-firstline
-lines =
content_of_random_file
-randomline
random_line( random_file( ... ) )
corf
Also speed could be improved, as I tried to write the code very readable, but wasted sometimes a little bit speed. (E.g. missing -check is translated to something like -check => sub{1}) As Functionality and Readability is more important than speed, I'll wait a little bit with speeding up :-)
Please feel free to suggest me anything what could be useful.
Oh, I hope none. I still have more test lines than function code. However, it's still BETA code.
Well, but because I want some random data, it's a little bit hard to test. So a test could be wrong, allthough everything is O.K.. To avoid it, I let many tests run, so that the chances for misproofing should be < 0.0000000001% or so. Even it has the disadvantage that the tests need really long :-(
I'm not definitly sure whether my test routines runs on OS, with path seperators different of '/', like in Win with '\\'. Perhaps anybody can try it and tell me the result. [But remember Win* is definitly the greater bug.]
This Program is free software. You can change or redistribute it under the same condition as Perl itself.
Copyright (c) 2002, Janek Schleicher, <bigj@kamelfreund.de>
Janek Schleicher, <bigj@kamelfreund.de>
Tie::Pick Data::Random
2 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
=back without =over
To install File::Random, copy and paste the appropriate command in to your terminal.
cpanm
cpanm File::Random
CPAN shell
perl -MCPAN -e shell install File::Random
For more information on module installation, please visit the detailed CPAN module installation guide.