NAME

File::Iterator - an object-oriented Perl module for iterating across files in a directory tree.

SYNOPSIS

        use File::Iterator;

        $it = new File::Iterator(
                DIR     => '/etc',
                RECURSE => 0,
                FILTER  => sub { $_[0] =~ /\.cf$/ },
        );

        while ($file = $it->next()) {
                # do stuff with $file
        }

INTRODUCTION

File::Iterator wraps a simple iteration interface around the files in a directory or directory tree. It builds a list of filenames, and maintains a cursor that points to one filename in the list. The user can work through the filenames sequentially by repeatedly doing stuff with the next filename that the cursor points to until their are no filenames left.

CONSTRUCTOR

new( [ DIR => '$somedir' ] [, RECURSE => 0 ] [, FILTER => sub { ... } ] [, RETURNDIRS => 1] [, FOLLOWSYMLINKS => 1] )

The constructor for a File::Iterator object. The starting directory for the iteration is specified as shown. If DIR is not specified, the current directory is used.

By default, File::Iterator works recursively, and will therefore list all files in the starting directory and all its subdirectories. To use File::Iterator non-recursively, set the RECURSE option to 0. Note that the module does not follow symbolic links to directories. To override this behaviour, set the FOLLOWSYMLINKS option to 1. Be careful though, as this can lead to endless iteration if a link points to a directory higher up its own directory tree.

Use the FILTER option to pass in a reference to a function to filter the files. Such a function will be passed the filename (including path) to filter and should return true if you are interested in that file.

        sub config {
                my $filename = shift;
                return 1 if $filename =~ /\.(cf|conf)$/; # only look for config files
        }
        
        $it = new File::Iterator(
                DIR => "/etc",
                FILTER => \&config
        );
        
        # or simply...
        
        $it = new File::Iterator(
                DIR => "/etc",
                FILTER => sub { $_[0] =~ /\.(cf|conf)$/ }
        );

Don't try to use the FILTER option to exclude subdirectories. This won't work:

        $it = new File::Iterator(
                DIR => "/etc",
                FILTER => sub { ! -d $_[0] }
        );

Set the RECURSE option to 0 instead.

By default, the module only returns filenames and not directory names (although the module will still search subdirectories if the RECURSE option is on). To return directory names as well as filenames, set the RETURNDIRS option to 1.

METHODS

next()

Returns the name of the next file (including the path) then advances the cursor, or returns undef if there are no more files to process. Note that because next() advances the cursor, the following code will produce erroneous results, because the two calls to next() return different values:

        while ($it->next()) {
                push @textfiles, $it->next() if -T $it->next();
        }

What you wanted to write was:

        while ($file = $it->next()) {
                push @textfiles, $file if -T $file;
        }

reset()

Resets the iterator so that the next call to next() returns the first file in the list.

ACKNOWLEDGEMENTS

Marius Feraru provided valuable input in the module's early days.

Jamie O'Shaughnessy <jos@cpan.org > was responsible for the reworking of the FILTER option in 0.07 and gave some good advice about avoiding unnecessary recursion.