The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
File-Next-0.36
River stage two • 20 direct dependents • 35 total dependents
14 ++
/ File::Next

NAME

File::Next - File-finding iterator

VERSION

Version 0.36

SYNOPSIS

File::Next is a lightweight, taint-safe file-finding module. It's lightweight and has no non-core prerequisites.

    use File::Next;

    my $files = File::Next->files( '/tmp' );

    while ( my $file = $files->() ) {
        # do something...
    }

OPERATIONAL THEORY

Each of the public functions in File::Next returns an iterator that will walk through a directory tree. The simplest use case is:

    use File::Next;

    my $iter = File::Next->files( '/tmp' );

    while ( my $file = $iter->() ) {
        print $file, "\n";
    }

    # Prints...
    /tmp/foo.txt
    /tmp/bar.pl
    /tmp/baz/1
    /tmp/baz/2.txt
    /tmp/baz/wango/tango/purple.txt

Note that only files are returned by files()'s iterator. Directories are ignored.

In list context, the iterator returns a list containing $dir, $file and $fullpath, where $fullpath is what would get returned in scalar context.

The first parameter to any of the iterator factory functions may be a hashref of parameters.

Note that the iterator will only return files, not directories.

PARAMETERS

file_filter -> \&file_filter

The file_filter lets you check to see if it's really a file you want to get back. If the file_filter returns a true value, the file will be returned; if false, it will be skipped.

The file_filter function takes no arguments but rather does its work through a collection of variables.

  • $_ is the current filename within that directory

  • $File::Next::dir is the current directory name

  • $File::Next::name is the complete pathname to the file

These are analogous to the same variables in File::Find.

    my $iter = File::Find::files( { file_filter => sub { /\.txt$/ } }, '/tmp' );

By default, the file_filter is sub {1}, or "all files".

descend_filter => \&descend_filter

The descend_filter lets you check to see if the iterator should descend into a given directory. Maybe you want to skip CVS and .svn directories.

    my $descend_filter = sub { $_ ne "CVS" && $_ ne ".svn" }

The descend_filter function takes no arguments but rather does its work through a collection of variables.

  • $_ is the current filename of the directory

  • $File::Next::dir is the complete directory name

The descend filter is NOT applied to any directory names specified in the constructor. For example,

    my $iter = File::Find::files( { descend_filter => sub{0} }, '/tmp' );

always descends into /tmp, as you would expect.

By default, the descend_filter is sub {1}, or "always descend".

error_handler => \&error_handler

If error_handler is set, then any errors will be sent through it. By default, this value is CORE::die.

sort_files => [ 0 | 1 | \&sort_sub]

If you want files sorted, pass in some true value, as in sort_files => 1.

If you want a special sort order, pass in a sort function like sort_files => sub { $a->[1] cmp $b->[1] }. Note that the parms passed in to the sub are arrayrefs, where $a->[0] is the directory name, $a->[1] is the file name and $a->[2] is the full path. Typically you're going to be sorting on $a->[2].

FUNCTIONS

files( { \%parameters }, @starting points )

Returns an iterator that walks directories starting with the items in @starting_points.

All file-finding in this module is adapted from Mark Jason Dominus' marvelous Higher Order Perl, page 126.

sort_standard( $a, $b )

A sort function for passing as a sort_files parameter:

    my $iter = File::Next::files( {
        sort_files => \&File::Next::sort_reverse
    }, 't/swamp' );

This function is the default, so the code above is identical to:

    my $iter = File::Next::files( {
        sort_files => \&File::Next::sort_reverse
    }, 't/swamp' );

sort_reverse( $a, $b )

Same as sort_standard, but in reverse.

The @queue that gets passed around is an array that has three elements for each of the entries in the queue: $dir, $file and $fullpath. Items must be pushed and popped off the queue three at a time (spliced, really).

Pulls out the files/dirs that might be worth looking into in $dir. If $dir is the empty string, then search the current directory. This is different than explicitly passing in a ".", because that will get prepended to the path names.

$parms is the hashref of parms passed into File::Next constructor.

reslash( $path )

Takes a path with all forward slashes and rebuilds it with whatever is appropriate for the platform. For example 'foo/bar/bat' will become 'foo\bar\bat' on Windows.

This is really just a convenience function.

AUTHOR

Andy Lester, <andy at petdance.com>

BUGS

Please report any bugs or feature requests to bug-file-next at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Next. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc File::Next

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2006 Andy Lester, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.