Next(3) User Contributed Perl Documentation Next(3)

# [NAME](#NAME)

File::Next - File-finding iterator

# [VERSION](#VERSION)

Version 1.18

# [SYNOPSIS](#SYNOPSIS)

File::Next is a lightweight, taint-safe file-finding module. It has no non-core prerequisites.

```
    use File::Next;
    my $files = File::Next::files( '/tmp' );
    while ( defined ( my $file = $files->() ) ) {
        # do something...
    }
```

# [OPERATIONAL THEORY](#OPERATIONAL_THEORY)

The two major functions, ***files()*** and **dirs()**, return an iterator that will walk through a directory tree. The simplest use case is:

```
    use File::Next;
    my $iter = File::Next::files( '/tmp' );
    while ( defined ( my $file = $iter->() ) ) {
        print $file, "\n";
    }
    # Prints...
    /tmp/foo.txt
    /tmp/bar.pl
    /tmp/baz/1
    /tmp/baz/2.txt
    /tmp/baz/wango/tango/purple.txt
```

Note that only files are returned by files()'s iterator. Directories are ignored.

In list context, the iterator returns a list containing *$dir*, *$file* and *$fullpath*, where *$fullpath* is what would get returned in scalar context.

The first parameter to any of the iterator factory functions may be a hashref of options.

# [ITERATORS](#ITERATORS)

For the three iterators, the \\%options are optional.

## [files( \[ \\%options, \] @starting\_points )](#files%28___)

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

## [dirs( \[ \\%options, \] @starting\_points )](#dirs%28___)

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

## [everything( \[ \\%options, \] @starting\_points )](#everything%28___)

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.

## [from\_file( \[ \\%options, \] $filename )](#from_file%28___)

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*.

# [SUPPORT FUNCTIONS](#SUPPORT_FUNCTIONS)

## [sort\_standard( $a, $b )](#sort_standard%28_$a,_$b_%29)

A sort function for passing as a "sort\_files" option:

```
    my $iter = File::Next::files( {
        sort_files => \&File::Next::sort_standard,
    }, 't/swamp' );
```

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

```
    my $iter = File::Next::files( {
        sort_files => 1,
    }, 't/swamp' );
```

## [sort\_reverse( $a, $b )](#sort_reverse%28_$a,_$b_%29)

Same as "sort\_standard", but in reverse.

## [reslash( $path )](#reslash%28_$path_%29)

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.

# [CONSTRUCTOR PARAMETERS](#CONSTRUCTOR_PARAMETERS)

## [file\_filter -> \\&file\_filter](#file_filter_)

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 File::Find.

```
    my $iter = File::Next::files( { 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.

## [descend\_filter => \\&descend\_filter](#descend_filter_=__)

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 = File::Next::files( { descend_filter => sub{0} }, '/tmp' );
```

always descends into */tmp*, as you would expect.

By default, the *descend\_filter* is "sub {1}", or "always descend".

## [error\_handler => \\&error\_handler](#error_handler_=__)

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.

## [warning\_handler => \\&warning\_handler](#warning_handler_=__)

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.

## [sort\_files => \[ 0 | 1 | \\&sort\_sub\]](#sort_files_=____0___1___)

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].

## [follow\_symlinks => \[ 0 | 1 \]](#follow_symlinks_=____0___1__)

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 File::Next must check to see if the file or directory you're about to follow is actually a symlink.

## [nul\_separated => \[ 0 | 1 \]](#nul_separated_=____0___1__)

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.

# [PRIVATE FUNCTIONS](#PRIVATE_FUNCTIONS)

## [\_setup( $default\_parms, @**whatever\_was\_passed\_to\_files()** )](#_setup%28_$default_parms,_@)

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.

## [\_candidate\_files( $parms, $dir )](#_candidate_files%28_$parms,_$dir_%29)

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 File::Next constructor.

# [DIAGNOSTICS](#DIAGNOSTICS)

"File::Next::files must not be invoked as File::Next->files"

"File::Next::dirs must not be invoked as File::Next->dirs"

"File::Next::everything must not be invoked as File::Next->everything"

The interface functions do not allow for the method invocation syntax and throw errors with the messages above. You can work around this limitation with "can" in UNIVERSAL.

```
    for my $file_system_feature (qw(dirs files)) {
        my $iterator = File::Next->can($file_system_feature)->($options, $target_directory);
        while (defined(my $name = $iterator->())) {
            # ...
        }
    }
```

# [SPEED TWEAKS](#SPEED_TWEAKS)

•

Don't set "follow\_symlinks => 0" unless you need it.

# [AUTHOR](#AUTHOR)

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

# [BUGS](#BUGS)

Please report any bugs or feature requests to <http://github.com/petdance/file-next/issues>.

Note that File::Next does NOT use <http://rt.cpan.org> for bug tracking.

# [SUPPORT](#SUPPORT)

You can find documentation for this module with the perldoc command.

```
    perldoc File::Next
```

You can also look for information at:

- File::Next's bug queue
  
  <http://github.com/petdance/file-next/issues>
- CPAN Ratings
  
  <http://cpanratings.perl.org/d/File-Next>
- Search CPAN
  
  <http://search.cpan.org/dist/File-Next>
- Source code repository
  
  <http://github.com/petdance/file-next/tree/master>

# [ACKNOWLEDGEMENTS](#ACKNOWLEDGEMENTS)

All file-finding in this module is adapted from Mark Jason Dominus' marvelous *Higher Order Perl*, page 126.

Thanks to these fine contributors: Varadinsky, Paulo Custodio, Gerhard Poul, Brian Fraser, Todd Rinaldo, Bruce Woodward, Christopher J. Madsen, Bernhard Fisseni and Rob Hoelz.

# [COPYRIGHT & LICENSE](#COPYRIGHT_&_LICENSE)

Copyright 2005-2017 Andy Lester.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

2026-10-25 perl v5.44.0

---

Document: File::Next(3pm) from perl-file-next 1.18-r9 (Chainguard OS)
Source: https://github.com/petdance/file-next