The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


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


        use File::Iterator;

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

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


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.


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.



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;

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


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

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

Paul Hoffman spotted that the test on $^O in versions pre-0.08 would recognise Darwin as a Windows OS. He probably saved my life. :-)


Copyright 2002 Simon Whitaker <>