1Next(3) User Contributed Perl Documentation Next(3)
2
6 File::Next - File-finding iterator
7
9 Version 1.18
10
12 File::Next is a lightweight, taint-safe file-finding module. It has no
13 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 from_file( [ \%options, ] $filename )
70 Returns an iterator that iterates over each of the files specified in
71 $filename. If $filename is "-", then the files are read from STDIN.
72 The files are assumed to be in the file one filename per line. If
74 $nul_separated is passed, then the files are assumed to be NUL-
75 separated, as by "find -print0".
76 If there are blank lines or empty filenames in the input stream, they
78 are ignored.
79 Each filename is checked to see that it is a regular file or a named
81 pipe. If the file does not exists or is a directory, then a warning is
82 thrown to warning_handler, and the file is skipped.
83 The following options have no effect in "from_files": descend_filter,
85 sort_files, follow_symlinks.
86
88 sort_standard( $a, $b )
89 A sort function for passing as a "sort_files" option:
90 my $iter = File::Next::files( {
92 sort_files => \&File::Next::sort_standard,
93 }, 't/swamp' );
94 This function is the default, so the code above is identical to:
96 my $iter = File::Next::files( {
98 sort_files => 1,
99 }, 't/swamp' );
100 sort_reverse( $a, $b )
102 Same as "sort_standard", but in reverse.
103 reslash( $path )
105 Takes a path with all forward slashes and rebuilds it with whatever is
106 appropriate for the platform. For example 'foo/bar/bat' will become
107 'foo\bar\bat' on Windows.
108 This is really just a convenience function. I'd make it private, but
110 ack wants it, too.
111
113 file_filter -> \&file_filter
114 The file_filter lets you check to see if it's really a file you want to
115 get back. If the file_filter returns a true value, the file will be
116 returned; if false, it will be skipped.
117 The file_filter function takes no arguments but rather does its work
119 through a collection of variables.
120 • $_ is the current filename within that directory
122 • $File::Next::dir is the current directory name
124 • $File::Next::name is the complete pathname to the file
126 These are analogous to the same variables in File::Find.
128 my $iter = File::Next::files( { file_filter => sub { /\.txt$/ } }, '/tmp' );
130 By default, the file_filter is "sub {1}", or "all files".
132 This filter has no effect if your iterator is only returning
134 directories.
135 descend_filter => \&descend_filter
137 The descend_filter lets you check to see if the iterator should descend
138 into a given directory. Maybe you want to skip CVS and .svn
139 directories.
140 my $descend_filter = sub { $_ ne "CVS" && $_ ne ".svn" }
142 The descend_filter function takes no arguments but rather does its work
144 through a collection of variables.
145 • $_ is the current filename of the directory
147 • $File::Next::dir is the complete directory name
149 The descend filter is NOT applied to any directory names specified as
151 @starting_points in the constructor. For example,
152 my $iter = File::Next::files( { descend_filter => sub{0} }, '/tmp' );
154 always descends into /tmp, as you would expect.
156 By default, the descend_filter is "sub {1}", or "always descend".
158 error_handler => \&error_handler
160 If error_handler is set, then any errors will be sent through it. If
161 the error is OS-related (ex. file not found, not permissions), the
162 native error code is passed as a second argument. By default, this
163 value is "CORE::die". This function must NOT return.
164 warning_handler => \&warning_handler
166 If warning_handler is set, then any errors will be sent through it. By
167 default, this value is "CORE::warn". Unlike the error_handler, this
168 function must return.
169 sort_files => [ 0 | 1 | \&sort_sub]
171 If you want files sorted, pass in some true value, as in "sort_files =>
172 1".
173 If you want a special sort order, pass in a sort function like
175 "sort_files => sub { $a->[1] cmp $b->[1] }". Note that the parms
176 passed in to the sub are arrayrefs, where $a->[0] is the directory
177 name, $a->[1] is the file name and $a->[2] is the full path. Typically
178 you're going to be sorting on $a->[2].
179 follow_symlinks => [ 0 | 1 ]
181 If set to false, the iterator will ignore any files and directories
182 that are actually symlinks. This has no effect on non-Unixy systems
183 such as Windows. By default, this is true.
184 Note that this filter does not apply to any of the @starting_points
186 passed in to the constructor.
187 You should not set "follow_symlinks => 0" unless you specifically need
189 that behavior. Setting "follow_symlinks => 0" can be a speed hit,
190 because File::Next must check to see if the file or directory you're
191 about to follow is actually a symlink.
192 nul_separated => [ 0 | 1 ]
194 Used by the "from_file" iterator. Specifies that the files listed in
195 the input file are separated by NUL characters, as from the "find"
196 command with the "-print0" argument.
197
199 _setup( $default_parms, @whatever_was_passed_to_files() )
200 Handles all the scut-work for setting up the parms passed in.
201 Returns a hashref of operational options, combined between
203 $passed_parms and $defaults, plus the queue.
204 The queue prep stuff takes the strings in @starting_points and puts
206 them in the format that queue needs.
207 The @queue that gets passed around is an array, with each entry an
209 arrayref of $dir, $file and $fullpath.
210 _candidate_files( $parms, $dir )
212 Pulls out the files/dirs that might be worth looking into in $dir. If
213 $dir is the empty string, then search the current directory.
214 $parms is the hashref of parms passed into File::Next constructor.
216
218 "File::Next::files must not be invoked as File::Next->files"
219 "File::Next::dirs must not be invoked as File::Next->dirs"
220 "File::Next::everything must not be invoked as File::Next->everything"
221 The interface functions do not allow for the method invocation syntax
223 and throw errors with the messages above. You can work around this
224 limitation with "can" in UNIVERSAL.
225 for my $file_system_feature (qw(dirs files)) {
227 my $iterator = File::Next->can($file_system_feature)->($options, $target_directory);
228 while (defined(my $name = $iterator->())) {
229 # ...
230 }
231 }
232
234 • Don't set "follow_symlinks => 0" unless you need it.
235
237 Andy Lester, "<andy at petdance.com>"
238
240 Please report any bugs or feature requests to
241 <http://github.com/petdance/file-next/issues>.
242 Note that File::Next does NOT use <http://rt.cpan.org> for bug
244 tracking.
245
247 You can find documentation for this module with the perldoc command.
248 perldoc File::Next
250 You can also look for information at:
252 • File::Next's bug queue
254 <http://github.com/petdance/file-next/issues>
256 • CPAN Ratings
258 <http://cpanratings.perl.org/d/File-Next>
260 • Search CPAN
262 <http://search.cpan.org/dist/File-Next>
264 • Source code repository
266 <http://github.com/petdance/file-next/tree/master>
268
270 All file-finding in this module is adapted from Mark Jason Dominus'
271 marvelous Higher Order Perl, page 126.
272 Thanks to these fine contributors: Varadinsky, Paulo Custodio, Gerhard
274 Poul, Brian Fraser, Todd Rinaldo, Bruce Woodward, Christopher J.
275 Madsen, Bernhard Fisseni and Rob Hoelz.
276
278 Copyright 2005-2017 Andy Lester.
279 This program is free software; you can redistribute it and/or modify it
281 under the terms of the Artistic License version 2.0.
282perl v5.38.0 2023-07-20 Next(3)