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 => 1,
    FILTER  => '*.cf',
  );

  while ($it->hasNext()) {
    $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 particular filename. The user can work through the filenames sequentially by doing stuff with the filename that the cursor points to and then advancing the cursor to the next filename in the list.

CONSTRUCTOR

new( [ DIR => '$somedir' ] [, RECURSE => 0 ] [, FILTER => '*.ext; filename.*' ] )

The constructor for a File::Iterator object. The root 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 root directory and all its subdirectories. To use File::Iterator non-recursively, set the RECURSE option to 0.

You can also optionally specify a filename filter using the FILTER option. Separate multiple filters with ; or , as shown.

METHODS

hasNext()

Evaluates to true while there are more files to process.

next()

Returns the name of the next file (including the path) and advances the cursor to the next filename. 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->hasNext()) {
                push @textfiles, $it->next() if -T $it->next();
        }

What you wanted to write was:

        while ($it->hasNext()) {
                $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.

AUTHOR

Copyright 2002 Simon Whitaker <swhitaker@cpan.org>