Description:

This module iterates over files and directories to identify ones
matching a user-defined set of rules. The API is based heavily on
File::Find::Rule, but with more explicit distinction between matching
rules and options that influence how directories are searched. A
"Path::Iterator::Rule" object is a collection of rules (match criteria)
with methods to add additional criteria. Options that control directory
traversal are given as arguments to the method that generates an
iterator.

Here is a summary of features for comparison to other file finding
modules:

* provides many "helper" methods for specifying rules

* offers (lazy) iterator and flattened list interfaces

* custom rules implemented with callbacks

* breadth-first (default) or pre- or post-order depth-first searching

* follows symlinks (by default, but can be disabled)

* directories visited only once (no infinite loop; can be disabled)

* doesn't chdir during operation

* provides an API for extensions

As a convenience, the PIR module is an empty subclass of this one that
is less arduous to type for one-liners.