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

NAME

6       File::Next - File-finding iterator
7

VERSION

9       Version 1.16
10

SYNOPSIS

12       File::Next is a lightweight, taint-safe file-finding module.  It's
13       lightweight and has no 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 that has three elements
209       for each of the entries in the queue: $dir, $file and $fullpath.  Items
210       must be pushed and popped off the queue three at a time (spliced,
211       really).
212
213   _candidate_files( $parms, $dir )
214       Pulls out the files/dirs that might be worth looking into in $dir.  If
215       $dir is the empty string, then search the current directory.
216
217       $parms is the hashref of parms passed into File::Next constructor.
218

DIAGNOSTICS

220       "File::Next::files must not be invoked as File::Next->files"
221       "File::Next::dirs must not be invoked as File::Next->dirs"
222       "File::Next::everything must not be invoked as File::Next->everything"
223
224       The interface functions do not allow for the method invocation syntax
225       and throw errors with the messages above. You can work around this
226       limitation with "can" in UNIVERSAL.
227
228           for my $file_system_feature (qw(dirs files)) {
229               my $iterator = File::Next->can($file_system_feature)->($options, $target_directory);
230               while (defined(my $name = $iterator->())) {
231                   # ...
232               }
233           }
234

SPEED TWEAKS

236       ·   Don't set "follow_symlinks => 0" unless you need it.
237

AUTHOR

239       Andy Lester, "<andy at petdance.com>"
240

BUGS

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

SUPPORT

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

ACKNOWLEDGEMENTS

276       All file-finding in this module is adapted from Mark Jason Dominus'
277       marvelous Higher Order Perl, page 126.
278
279       Thanks also for bug fixes and typo finding to Gerhard Poul, Brian
280       Fraser, Todd Rinaldo, Bruce Woodward, Christopher J. Madsen, Bernhard
281       Fisseni and Rob Hoelz.
282
284       Copyright 2005-2016 Andy Lester.
285
286       This program is free software; you can redistribute it and/or modify it
287       under the terms of the Artistic License version 2.0.
288
289
290
291perl v5.28.1                      2016-07-08                           Next(3)
Impressum