File/Random version 0.08
========================
NAME
File::Random - Perl module for random selecting of a file
SYNOPSIS
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');
DESCRIPTION
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.
FUNCTION random_file
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
);
-dir
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.
-check
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).
-recursive
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
:-)
FUNCTION content_of_random_file
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.
EXPORT
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/;".
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.
DEPENDENCIES
This module requires these other modules and libraries:
Test::More
Test::Exception
Test::Class
Set::Scalar
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 to
install the modules anyway).
COPYRIGHT
This Program is free software. You can change or redistribute it under
the same condition as Perl itself.
Copyright (c) 2002, Janek Schleicher, <
[email protected]>
AUTHOR
Janek Schleicher, <
[email protected]>
SEE ALSO
the Tie::Pick manpage
the Data::Random manpage
