Manpages - File_Next.3pm

Returns an iterator that walks directories starting with the items in @starting_points. Each call to the iterator returns another regular file.

Returns an iterator that walks directories starting with the items in @starting_points. Each call to the iterator returns another directory.

Returns an iterator that walks directories starting with the items in @starting_points. Each call to the iterator returns another file, whether it’s a regular file, directory, symlink, socket, or whatever.

Returns an iterator that iterates over each of the files specified in $filename. If $filename is -, then the files are read from STDIN.

The files are assumed to be in the file one filename per line. If $nul_separated is passed, then the files are assumed to be NUL-separated, as by find -print0.

If there are blank lines or empty filenames in the input stream, they are ignored.

Each filename is checked to see that it is a regular file or a named pipe. If the file does not exists or is a directory, then a warning is thrown to warning_handler, and the file is skipped.

The following options have no effect in from_files: descend_filter, sort_files, follow_symlinks.

A sort function for passing as a sort_files option:

my $iter = ( { sort_files => \&, }, t/swamp );

This function is the default, so the code above is identical to:

my $iter = ( { sort_files => 1, }, t/swamp );

Same as sort_standard, but in reverse.

Takes a path with all forward slashes and rebuilds it with whatever is appropriate for the platform. For example ’foo/bar/bat’ will become ’foo\bar\bat’ on Windows.

This is really just a convenience function. I’d make it private, but ack wants it, too.

The file_filter lets you check to see if it’s really a file you want to get back. If the file_filter returns a true value, the file will be returned; if false, it will be skipped.

The file_filter function takes no arguments but rather does its work through a collection of variables.

• $_ is the current filename within that directory
• $File::Next::dir is the current directory name
• $File::Next::name is the complete pathname to the file

These are analogous to the same variables in :Find.

my $iter = ( { file_filter => sub { \.txt$ } }, /tmp );

By default, the file_filter is sub {1}, or all files.

This filter has no effect if your iterator is only returning directories.

The descend_filter lets you check to see if the iterator should descend into a given directory. Maybe you want to skip CVS and .svn directories.

my $descend_filter = sub { $_ ne “CVS” && $_ ne “.svn” }

The descend_filter function takes no arguments but rather does its work through a collection of variables.

• $_ is the current filename of the directory
• $File::Next::dir is the complete directory name

The descend filter is NOT applied to any directory names specified as @starting_points in the constructor. For example,

my $iter = ( { descend_filter => sub{0} }, /tmp );

always descends into /tmp, as you would expect.

By default, the descend_filter is sub {1}, or always descend.

If error_handler is set, then any errors will be sent through it. If the error is OS-related (ex. file not found, not permissions), the native error code is passed as a second argument. By default, this value is CORE::die. This function must NOT return.

If warning_handler is set, then any errors will be sent through it. By default, this value is CORE::warn. Unlike the error_handler, this function must return.

If you want files sorted, pass in some true value, as in sort_files => 1.

If you want a special sort order, pass in a sort function like sort_files => sub { $a->[1] cmp $b->[1] }. Note that the parms passed in to the sub are arrayrefs, where $a->[0] is the directory name, $a->[1] is the file name and $a->[2] is the full path. Typically you’re going to be sorting on $a->[2].

If set to false, the iterator will ignore any files and directories that are actually symlinks. This has no effect on non-Unixy systems such as Windows. By default, this is true.

Note that this filter does not apply to any of the @starting_points passed in to the constructor.

You should not set follow_symlinks => 0 unless you specifically need that behavior. Setting follow_symlinks => 0 can be a speed hit, because :Next must check to see if the file or directory you’re about to follow is actually a symlink.

Used by the from_file iterator. Specifies that the files listed in the input file are separated by NUL characters, as from the find command with the -print0 argument.

Handles all the scut-work for setting up the parms passed in.

Returns a hashref of operational options, combined between $passed_parms and $defaults, plus the queue.

The queue prep stuff takes the strings in @starting_points and puts them in the format that queue needs.

The @queue that gets passed around is an array, with each entry an arrayref of $dir, $file and $fullpath.

Pulls out the files/dirs that might be worth looking into in $dir. If $dir is the empty string, then search the current directory.

$parms is the hashref of parms passed into :Next constructor.