File/Random version 0.03
========================

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$/);
                                                           
      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];
 
  FUNCTIONS

    random_file(-dir => $dir, -check => $sub_or_re)
        Returns a randomly selected file(name) from the specified directory
        If the directory is empty, undef will be returned.

        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.

        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.

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

If you don't have Test::More, Test::Exception or Set::Scalar installed,
make test will produce errors.
You can work with the module even without them. 

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

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, <bigj@kamelfreund.de>
