1Next(3)               User Contributed Perl Documentation              Next(3)
2
3
4

NAME

6       File::Next - File-finding iterator
7

VERSION

9       Version 1.18
10

SYNOPSIS

12       File::Next is a lightweight, taint-safe file-finding module.  It has no
13       non-core prerequisites.
14
15           use File::Next;
16
17           my $files = File::Next::files( '/tmp' );
18
19           while ( defined ( my $file = $files->() ) ) {
20               # do something...
21           }
22

OPERATIONAL THEORY

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
27           use File::Next;
28
29           my $iter = File::Next::files( '/tmp' );
30
31           while ( defined ( my $file = $iter->() ) ) {
32               print $file, "\n";
33           }
34
35           # 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
42       Note that only files are returned by files()'s iterator.  Directories
43       are ignored.
44
45       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
49       The first parameter to any of the iterator factory functions may be a
50       hashref of options.
51

ITERATORS

53       For the three iterators, the \%options are optional.
54
55   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
60   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
64   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
69   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
73       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
77       If there are blank lines or empty filenames in the input stream, they
78       are ignored.
79
80       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
84       The following options have no effect in "from_files": descend_filter,
85       sort_files, follow_symlinks.
86

SUPPORT FUNCTIONS

88   sort_standard( $a, $b )
89       A sort function for passing as a "sort_files" option:
90
91           my $iter = File::Next::files( {
92               sort_files => \&File::Next::sort_standard,
93           }, 't/swamp' );
94
95       This function is the default, so the code above is identical to:
96
97           my $iter = File::Next::files( {
98               sort_files => 1,
99           }, 't/swamp' );
100
101   sort_reverse( $a, $b )
102       Same as "sort_standard", but in reverse.
103
104   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
109       This is really just a convenience function.  I'd make it private, but
110       ack wants it, too.
111

CONSTRUCTOR PARAMETERS

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
118       The file_filter function takes no arguments but rather does its work
119       through a collection of variables.
120
121       •   $_ is the current filename within that directory
122
123       •   $File::Next::dir is the current directory name
124
125       •   $File::Next::name is the complete pathname to the file
126
127       These are analogous to the same variables in File::Find.
128
129           my $iter = File::Next::files( { file_filter => sub { /\.txt$/ } }, '/tmp' );
130
131       By default, the file_filter is "sub {1}", or "all files".
132
133       This filter has no effect if your iterator is only returning
134       directories.
135
136   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
141           my $descend_filter = sub { $_ ne "CVS" && $_ ne ".svn" }
142
143       The descend_filter function takes no arguments but rather does its work
144       through a collection of variables.
145
146       •   $_ is the current filename of the directory
147
148       •   $File::Next::dir is the complete directory name
149
150       The descend filter is NOT applied to any directory names specified as
151       @starting_points in the constructor.  For example,
152
153           my $iter = File::Next::files( { descend_filter => sub{0} }, '/tmp' );
154
155       always descends into /tmp, as you would expect.
156
157       By default, the descend_filter is "sub {1}", or "always descend".
158
159   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
165   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
170   sort_files => [ 0 | 1 | \&sort_sub]
171       If you want files sorted, pass in some true value, as in "sort_files =>
172       1".
173
174       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
180   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
185       Note that this filter does not apply to any of the @starting_points
186       passed in to the constructor.
187
188       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
193   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

PRIVATE FUNCTIONS

199   _setup( $default_parms, @whatever_was_passed_to_files() )
200       Handles all the scut-work for setting up the parms passed in.
201
202       Returns a hashref of operational options, combined between
203       $passed_parms and $defaults, plus the queue.
204
205       The queue prep stuff takes the strings in @starting_points and puts
206       them in the format that queue needs.
207
208       The @queue that gets passed around is an array, with each entry an
209       arrayref of $dir, $file and $fullpath.
210
211   _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
215       $parms is the hashref of parms passed into File::Next constructor.
216

DIAGNOSTICS

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
222       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
226           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

SPEED TWEAKS

234       •   Don't set "follow_symlinks => 0" unless you need it.
235

AUTHOR

237       Andy Lester, "<andy at petdance.com>"
238

BUGS

240       Please report any bugs or feature requests to
241       <http://github.com/petdance/file-next/issues>.
242
243       Note that File::Next does NOT use <http://rt.cpan.org> for bug
244       tracking.
245

SUPPORT

247       You can find documentation for this module with the perldoc command.
248
249           perldoc File::Next
250
251       You can also look for information at:
252
253       •   File::Next's bug queue
254
255           <http://github.com/petdance/file-next/issues>
256
257       •   CPAN Ratings
258
259           <http://cpanratings.perl.org/d/File-Next>
260
261       •   Search CPAN
262
263           <http://search.cpan.org/dist/File-Next>
264
265       •   Source code repository
266
267           <http://github.com/petdance/file-next/tree/master>
268

ACKNOWLEDGEMENTS

270       All file-finding in this module is adapted from Mark Jason Dominus'
271       marvelous Higher Order Perl, page 126.
272
273       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
280       This program is free software; you can redistribute it and/or modify it
281       under the terms of the Artistic License version 2.0.
282
283
284
285perl v5.38.0                      2023-07-20                           Next(3)
Impressum