perl6-concurrent-file-find

concurrent File::Find for Perl 6

SYNOPSIS

use v6;
use Concurrent::File::Find;

find(%*ENV<HOME>
    , :extension('txt', {.contains('~')}) # ends in .txt or ends in something that contains a ~
    , :exclude('covers') # exclude any path that contains covers, both for files and directories
    , :exclude-dir('.') # exclude any directory-path that contains a . 
    , :file # return file paths
    , :!directory # don't return directory paths
    , :symlink # return symlink paths
    , :max-depth(5) # but not deeper then 5 directories deep
    , :follow-symlink # follow symlinks (no loop detection yet)
    , :keep-going # on error (no access, stale symlink, etc.), keep going
    , :quiet # don't report errors on STDERR
).elems.say; # count how many files and symlinks we got

sleep 10;

my @l := find-simple(%*ENV<HOME>, :keep-going, :!no-thread); # binding to avoid eagerness

for @l {
    @l.channel.close if $++ > 5000; # hard-close the channel after 5000 found files
    .say if $++ %% 100 # print every 100th file
}

DESCRIPTION

Routines

sub find

Return List of files, directories and symlinks as Str that are fetched by a background thread. The list got a role mixed in with the sole method channel that can be used to close the channel behind the List to abort any still ongoing fetching. This is a bit wonky and may produce a warning when the underlying Promise is DESTROYed. There are various inclusive and exclusive filter options as described below. Files are sorted before directories in the returned list for any directory. Only after items are returned recursion into sub-directories may occur.

Matcher

Some arguments take a matcher or a list of matchers. The Junction-type used when given a list depends on the argument. As matchers Str, Regex, and Callable are accepted. Unless stated otherwise Str matches partially and case sensitive against the filename or the whole path. Regexp smartmatches against IO::Path.Str and Callable is called with IO::Path.

Arguments

IO(Str) $dir - directory where to start either as IO::Path or Str.

:$file = True - also return files

:$directory - also return directories

:$symlink - also return symlinks

:&return-type = { .IO.Str } - transform the matched items to Str by default. The block is fed with IO::Path objects. The result is returned as is and not used by find itself, you can go wild here.

:$name - return any file in any directory that matches provided matcher. Using Str as matcher requires exact, case sensitive match.

:$include - return any file where IO::Path.basename matches provided matcher. Using Str as matcher requires partial match.

:$exclude - do not return any file where IO::Path.basename matches provided matcher. Using Str as matcher requires partial match.

:$include-dir - do return or decent into directories that match provided matcher. Using Str as matcher requires partial match.

:$exclude-dir - do not return or decent into directories that match provided matcher. Using Str as matcher requires partial match.

:$extension - return any item that matches IO::Path.extension. Using Str as matcher requires exact, case sensitive match.

:$recursive = True - descent into sub-directories.

Int :$max-depth = ∞ - descent as deep into sub-directories.

:$follow-symlink = False - follow symlinks. There is no loop detection yet.

:$keep-going = True - on errors (access denied, stale symlinks, etc.) keek going but output warning on $*ERR.

:$quiet = False - in conjunction with $keep-going, do not outout warnings.

:$no-thread = False - disable creation of Promise. Useful for debugging.

sub find-simple

Same as find but without filter options, always recursive, follows existing symlinks (no loop detection yet) and no sorting. Faster and may contain less bugs. It may throw X::IO::StaleSymlink.

Arguments

IO(Str) $dir - Path as IO::Path or Str at where to start looking for files

:$keep-going = True - don't stop at errors

:$no-thread = False - don't create a Promise, useful for debugging

Exceptions

X::IO::NotADirectory does X::IO

Try do get the content of a path that is not a directory.

X::IO::CanNotAccess does X::IO

Access to a directroy is denied by the OS.

X::IO::StaleSymlink does X::IO

We where ment to return or follow a symlink that does exists but got no target.

X::Paramenter::Exclusive is Exception

Named arguments where used together that are mutual exclusive.

CAVEATS

Loop detection is not supported yet. As soon as there are portable versions for readlink and/or stat, loop detection will be added. Until then avoid :follow-symlink or use :max-depth.