File/Random version 0.04
========================
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});

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.

       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.

       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 switch recursive on slowers the program a bit :-)

 EXPORT

   None by default.

   You can export the function random_file with "use File::Random
   qw/random_file/;" or with the more simple "use File::Random qw/:all/;".

DEPENDENCIES

This module requires these other modules and libraries:

 Test::More
 Test::Exception
 Set::Scalar

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

SEE ALSO
   the Tie::Pick manpage the Tie::Select manpage the Data::Random manpage

COPYRIGHT AND LICENCE

This module is free software.
You can change and redistribute it under the same condition as Perl self.

Copyright (C) 2002 Janek Schleicher, <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.