1Next(3) User Contributed Perl Documentation Next(3)
2
6 File::Next - File-finding iterator
7
9 Version 1.02
10
12 File::Next is a lightweight, taint-safe file-finding module. It's
13 lightweight and has no non-core prerequisites.
14 use File::Next;
16 my $files = File::Next::files( '/tmp' );
18 while ( defined ( my $file = $files->() ) ) {
20 # do something...
21 }
22
24 The two major functions, files() and dirs(), return an iterator that
25 will walk through a directory tree. The simplest use case is:
26 use File::Next;
28 my $iter = File::Next::files( '/tmp' );
30 while ( defined ( my $file = $iter->() ) ) {
32 print $file, "\n";
33 }
34 # Prints...
36 /tmp/foo.txt
37 /tmp/bar.pl
38 /tmp/baz/1
39 /tmp/baz/2.txt
40 /tmp/baz/wango/tango/purple.txt
41 Note that only files are returned by "files()"'s iterator. Directories
43 are ignored.
44 In list context, the iterator returns a list containing $dir, $file and
46 $fullpath, where $fullpath is what would get returned in scalar con‐
47 text.
48 The first parameter to any of the iterator factory functions may be a
50 hashref of options.
51
53 For the three iterators, the \%options are optional.
54 files( [ \%options, ] @starting_points )
56 Returns an iterator that walks directories starting with the items in
58 @starting_points. Each call to the iterator returns another regular
59 file.
60 dirs( [ \%options, ] @starting_points )
62 Returns an iterator that walks directories starting with the items in
64 @starting_points. Each call to the iterator returns another directory.
65 everything( [ \%options, ] @starting_points )
67 Returns an iterator that walks directories starting with the items in
69 @starting_points. Each call to the iterator returns another file,
70 whether it's a regular file, directory, symlink, socket, or whatever.
71
73 sort_standard( $a, $b )
74 A sort function for passing as a "sort_files" option:
76 my $iter = File::Next::files( {
78 sort_files => \&File::Next::sort_standard,
79 }, 't/swamp' );
80 This function is the default, so the code above is identical to:
82 my $iter = File::Next::files( {
84 sort_files => 1,
85 }, 't/swamp' );
86 sort_reverse( $a, $b )
88 Same as "sort_standard", but in reverse.
90 reslash( $path )
92 Takes a path with all forward slashes and rebuilds it with whatever is
94 appropriate for the platform. For example 'foo/bar/bat' will become
95 'foo\bar\bat' on Windows.
96 This is really just a convenience function. I'd make it private, but
98 ack wants it, too.
99
101 file_filter -> \&file_filter
102 The file_filter lets you check to see if it's really a file you want to
104 get back. If the file_filter returns a true value, the file will be
105 returned; if false, it will be skipped.
106 The file_filter function takes no arguments but rather does its work
108 through a collection of variables.
109 * $_ is the current filename within that directory
111 * $File::Next::dir is the current directory name
112 * $File::Next::name is the complete pathname to the file
113 These are analogous to the same variables in File::Find.
115 my $iter = File::Next::files( { file_filter => sub { /\.txt$/ } }, '/tmp' );
117 By default, the file_filter is "sub {1}", or "all files".
119 This filter has no effect if your iterator is only returning directo‐
121 ries.
122 descend_filter => \&descend_filter
124 The descend_filter lets you check to see if the iterator should descend
126 into a given directory. Maybe you want to skip CVS and .svn directo‐
127 ries.
128 my $descend_filter = sub { $_ ne "CVS" && $_ ne ".svn" }
130 The descend_filter function takes no arguments but rather does its work
132 through a collection of variables.
133 * $_ is the current filename of the directory
135 * $File::Next::dir is the complete directory name
136 The descend filter is NOT applied to any directory names specified in
138 as @starting_points in the constructor. For example,
139 my $iter = File::Next::files( { descend_filter => sub{0} }, '/tmp' );
141 always descends into /tmp, as you would expect.
143 By default, the descend_filter is "sub {1}", or "always descend".
145 error_handler => \&error_handler
147 If error_handler is set, then any errors will be sent through it. By
149 default, this value is "CORE::die".
150 sort_files => [ 0 ⎪ 1 ⎪ \&sort_sub]
152 If you want files sorted, pass in some true value, as in "sort_files =>
154 1".
155 If you want a special sort order, pass in a sort function like
157 "sort_files => sub { $a->[1] cmp $b->[1] }". Note that the parms
158 passed in to the sub are arrayrefs, where $a->[0] is the directory
159 name, $a->[1] is the file name and $a->[2] is the full path. Typically
160 you're going to be sorting on $a->[2].
161 follow_symlinks => [ 0 ⎪ 1 ]
163 If set to false, the iterator will ignore any files and directories
165 that are actually symlinks. This has no effect on non-Unixy systems
166 such as Windows. By default, this is true.
167 Note that this filter does not apply to any of the @starting_points
169 passed in to the constructor.
170
172 _setup( $default_parms, @whatever_was_passed_to_files() )
173 Handles all the scut-work for setting up the parms passed in.
175 Returns a hashref of operational options, combined between
177 $passed_parms and $defaults, plus the queue.
178 The queue prep stuff takes the strings in @starting_points and puts
180 them in the format that queue needs.
181 The @queue that gets passed around is an array that has three elements
183 for each of the entries in the queue: $dir, $file and $fullpath. Items
184 must be pushed and popped off the queue three at a time (spliced,
185 really).
186 _candidate_files( $parms, $dir )
188 Pulls out the files/dirs that might be worth looking into in $dir. If
190 $dir is the empty string, then search the current directory.
191 $parms is the hashref of parms passed into File::Next constructor.
193
195 Andy Lester, "<andy at petdance.com>"
196
198 Please report any bugs or feature requests to
199 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-Next>. Note that
200 File::Next does NOT use rt.cpan.org for bug tracking.
201
203 You can find documentation for this module with the perldoc command.
204 perldoc File::Next
206 You can also look for information at:
208 * File::Next's bug queue
210 <http://code.google.com/p/file-next/issues/list>
211 * AnnoCPAN: Annotated CPAN documentation
213 <http://annocpan.org/dist/File-Next>
214 * CPAN Ratings
216 <http://cpanratings.perl.org/d/File-Next>
217 * Search CPAN
219 <http://search.cpan.org/dist/File-Next>
220 * Subversion repository
222 <https://file-next.googlecode.com/svn/trunk>
223
225 All file-finding in this module is adapted from Mark Jason Dominus'
226 marvelous Higher Order Perl, page 126.
227
229 Copyright 2006-2008 Andy Lester, all rights reserved.
230 This program is free software; you can redistribute it and/or modify it
232 under the same terms as Perl itself.
233perl v5.8.8 2008-01-14 Next(3)