Documentation for sub dir

Documentation for sub dir, assembled from the following types:

class IO::Path

From IO::Path

(IO::Path) routine dir

sub    dir(Cool $path = '.', Mu :$test = none('.', '..'))
method dir(IO::Path:D: Mu :$test = none('.', '..'))

Returns the contents of a directory as a lazy list of IO::Path objects representing relative paths, filtered by smart-matching their names against the :test parameter.

Examples:

# To iterate over the contents of the current directory:
for dir() -> $file {
    say $file;
}

# As before, but include even '.' and '..' which are filtered out by
# the default :test matcher:
for dir(test => *) -> $file {
    say $file;
}

# To get the names of all .jpg and .jpeg files in ~/Downloads:
my @jpegs = "%*ENV<HOME>/Downloads".IO.dir(test => /:i '.' jpe?g $/)».Str;

An example program that lists all files and directories recursively:

sub MAIN($dir = '.') {
    my @todo = $dir.IO;
    while @todo {
        for @todo.pop.dir -> $path {
            say $path.Str;
            @todo.push: $path if $path.d;
        }
    }
}

A lazy way to find the first three files ending in ".p6" recursively starting from the current directory:

my @stack = '.';
my $perl-files := gather while ( @stack ) {
    my $current = @stack.pop;
    take $current if ($current.IO.f && $current.IO.extension ~~ rx:i/p6$/);
    @stack.append(dir($current)>>.path) if $current.IO.d;
}
say $perl-files[1..3];