1Next(3) User Contributed Perl Documentation Next(3)
2
6 File::Next - File-finding iterator
7
9 Version 1.06
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
47 context.
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
57 @starting_points. Each call to the iterator returns another regular
58 file.
59 dirs( [ \%options, ] @starting_points )
61 Returns an iterator that walks directories starting with the items in
62 @starting_points. Each call to the iterator returns another directory.
63 everything( [ \%options, ] @starting_points )
65 Returns an iterator that walks directories starting with the items in
66 @starting_points. Each call to the iterator returns another file,
67 whether it's a regular file, directory, symlink, socket, or whatever.
68
70 sort_standard( $a, $b )
71 A sort function for passing as a "sort_files" option:
72 my $iter = File::Next::files( {
74 sort_files => \&File::Next::sort_standard,
75 }, 't/swamp' );
76 This function is the default, so the code above is identical to:
78 my $iter = File::Next::files( {
80 sort_files => 1,
81 }, 't/swamp' );
82 sort_reverse( $a, $b )
84 Same as "sort_standard", but in reverse.
85 reslash( $path )
87 Takes a path with all forward slashes and rebuilds it with whatever is
88 appropriate for the platform. For example 'foo/bar/bat' will become
89 'foo\bar\bat' on Windows.
90 This is really just a convenience function. I'd make it private, but
92 ack wants it, too.
93
95 file_filter -> \&file_filter
96 The file_filter lets you check to see if it's really a file you want to
97 get back. If the file_filter returns a true value, the file will be
98 returned; if false, it will be skipped.
99 The file_filter function takes no arguments but rather does its work
101 through a collection of variables.
102 · $_ is the current filename within that directory
104 · $File::Next::dir is the current directory name
106 · $File::Next::name is the complete pathname to the file
108 These are analogous to the same variables in File::Find.
110 my $iter = File::Next::files( { file_filter => sub { /\.txt$/ } }, '/tmp' );
112 By default, the file_filter is "sub {1}", or "all files".
114 This filter has no effect if your iterator is only returning
116 directories.
117 descend_filter => \&descend_filter
119 The descend_filter lets you check to see if the iterator should descend
120 into a given directory. Maybe you want to skip CVS and .svn
121 directories.
122 my $descend_filter = sub { $_ ne "CVS" && $_ ne ".svn" }
124 The descend_filter function takes no arguments but rather does its work
126 through a collection of variables.
127 · $_ is the current filename of the directory
129 · $File::Next::dir is the complete directory name
131 The descend filter is NOT applied to any directory names specified in
133 as @starting_points in the constructor. For example,
134 my $iter = File::Next::files( { descend_filter => sub{0} }, '/tmp' );
136 always descends into /tmp, as you would expect.
138 By default, the descend_filter is "sub {1}", or "always descend".
140 error_handler => \&error_handler
142 If error_handler is set, then any errors will be sent through it. By
143 default, this value is "CORE::die".
144 sort_files => [ 0 | 1 | \&sort_sub]
146 If you want files sorted, pass in some true value, as in "sort_files =>
147 1".
148 If you want a special sort order, pass in a sort function like
150 "sort_files => sub { $a->[1] cmp $b->[1] }". Note that the parms
151 passed in to the sub are arrayrefs, where $a->[0] is the directory
152 name, $a->[1] is the file name and $a->[2] is the full path. Typically
153 you're going to be sorting on $a->[2].
154 follow_symlinks => [ 0 | 1 ]
156 If set to false, the iterator will ignore any files and directories
157 that are actually symlinks. This has no effect on non-Unixy systems
158 such as Windows. By default, this is true.
159 Note that this filter does not apply to any of the @starting_points
161 passed in to the constructor.
162 You should not set "follow_symlinks => 0" unless you specifically need
164 that behavior. Setting "follow_symlinks => 0" can be a speed hit,
165 because File::Next must check to see if the file or directory you're
166 about to follow is actually a symlink.
167
169 _setup( $default_parms, @whatever_was_passed_to_files() )
170 Handles all the scut-work for setting up the parms passed in.
171 Returns a hashref of operational options, combined between
173 $passed_parms and $defaults, plus the queue.
174 The queue prep stuff takes the strings in @starting_points and puts
176 them in the format that queue needs.
177 The @queue that gets passed around is an array that has three elements
179 for each of the entries in the queue: $dir, $file and $fullpath. Items
180 must be pushed and popped off the queue three at a time (spliced,
181 really).
182 _candidate_files( $parms, $dir )
184 Pulls out the files/dirs that might be worth looking into in $dir. If
185 $dir is the empty string, then search the current directory.
186 $parms is the hashref of parms passed into File::Next constructor.
188
190 · Don't set "follow_symlinks => 0" unless you need it.
191
193 Andy Lester, "<andy at petdance.com>"
194
196 Please report any bugs or feature requests to
197 http://github.com/petdance/file-next/issues
198 <http://github.com/petdance/file-next/issues>.
199 Note that File::Next does NOT use <http://rt.cpan.org> for bug
201 tracking.
202
204 You can find documentation for this module with the perldoc command.
205 perldoc File::Next
207 You can also look for information at:
209 · File::Next's bug queue
211 http://github.com/petdance/file-next/issues
213 <http://github.com/petdance/file-next/issues>
214 · AnnoCPAN: Annotated CPAN documentation
216 http://annocpan.org/dist/File-Next <http://annocpan.org/dist/File-
218 Next>
219 · CPAN Ratings
221 http://cpanratings.perl.org/d/File-Next
223 <http://cpanratings.perl.org/d/File-Next>
224 · Search CPAN
226 http://search.cpan.org/dist/File-Next
228 <http://search.cpan.org/dist/File-Next>
229 · Source code repository
231 http://github.com/petdance/file-next/tree/master
233 <http://github.com/petdance/file-next/tree/master>
234
236 All file-finding in this module is adapted from Mark Jason Dominus'
237 marvelous Higher Order Perl, page 126.
238
240 Copyright 2005-2009 Andy Lester.
241 This program is free software; you can redistribute it and/or modify it
243 under the terms of either:
244 · the GNU General Public License as published by the Free Software
246 Foundation; either version 1, or (at your option) any later
247 version, or
248 · the Artistic License version 2.0.
250perl v5.12.0 2009-08-04 Next(3)