File::Next - File-finding iterator
Version 1.00
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 ( defined ( my $file = $files->() ) ) { # do something... }
The two major functions, files() and dirs(), return an iterator that will walk through a directory tree. The simplest use case is:
use File::Next; my $iter = File::Next::files( '/tmp' ); while ( defined ( 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.
files()
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 options.
For the three iterators, the \%options are optional.
Returns an iterator that walks directories starting with the items in @starting_points. Each call to the iterator returns another regular file.
Returns an iterator that walks directories starting with the items in @starting_points. Each call to the iterator returns another directory.
Returns an iterator that walks directories starting with the items in @starting_points. Each call to the iterator returns another file, whether it's a regular file, directory, symlink, socket, or whatever.
A sort function for passing as a sort_files option:
sort_files
my $iter = File::Next::files( { sort_files => \&File::Next::sort_standard, }, 't/swamp' );
This function is the default, so the code above is identical to:
my $iter = File::Next::files( { sort_files => 1, }, 't/swamp' );
Same as sort_standard, but in reverse.
sort_standard
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. I'd make it private, but ack wants it, too.
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::dir
$File::Next::name is the complete pathname to the file
$File::Next::name
These are analogous to the same variables in File::Find.
my $iter = File::Next::files( { file_filter => sub { /\.txt$/ } }, '/tmp' );
By default, the file_filter is sub {1}, or "all files".
sub {1}
This filter has no effect if your iterator is only returning directories.
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 as @starting_points in the constructor. For example,
my $iter = File::Next::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".
If error_handler is set, then any errors will be sent through it. By default, this value is CORE::die.
CORE::die
If you want files sorted, pass in some true value, as in sort_files => 1.
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].
sort_files => sub { $a->[1] cmp $b->[1] }
If set to false, the iterator will ignore any files and directories that are actually symlinks. This has no effect on non-Unixy systems such as Windows. By default, this is true.
Note that this filter does not apply to any of the @starting_points passed in to the constructor.
Handles all the scut-work for setting up the parms passed in.
Returns a hashref of operational options, combined between $passed_parms and $defaults, plus the queue.
The queue prep stuff takes the strings in @starting_points and puts them in the format that queue needs.
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).
@queue
Pulls out the files/dirs that might be worth looking into in $dir. If $dir is the empty string, then search the current directory.
$parms is the hashref of parms passed into File::Next constructor.
Andy Lester, <andy at petdance.com>
<andy at petdance.com>
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.
bug-file-next at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc File::Next
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/File-Next
CPAN Ratings
http://cpanratings.perl.org/d/File-Next
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-Next
Search CPAN
http://search.cpan.org/dist/File-Next
Subversion repository
https://file-next.googlecode.com/svn/trunk
All file-finding in this module is adapted from Mark Jason Dominus' marvelous Higher Order Perl, page 126.
Copyright 2006-2007 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.
To install File::Next, copy and paste the appropriate command in to your terminal.
cpanm
cpanm File::Next
CPAN shell
perl -MCPAN -e shell install File::Next
For more information on module installation, please visit the detailed CPAN module installation guide.