=title module Zef::Utils::FileSystem

=subtitle Utility subroutines for interacting with the file system

Synopsis

    use Zef::Utils::FileSystem;
    # Recursively list, copy, move, or delete paths
    my @files_in_lib      = list-paths("lib/");
    my @copied_to_lib2    = copy-paths("lib/", "lib2/");
    my @moved_to_lib3     = move-paths("lib2/", "lib3/");
    my @deleted_from_lib3 = delete-paths("lib3/");
    # Locate a bin script from $PATH
    my $zef_in_path = Zef::Utils::FileSystem::which("zef");
    say "zef bin location: {$zef_in_path // 'n/a'}";
    # A Lock.protect like interface that is backed by a file lock
    my $lock-file = $*TMP.add("myapp.lock");
    lock-file-protect($lock-file, {
        # do some work here that may want to use cross-process locking
    });

Description

Provides additional facilities for interacting with the file system.

Subroutines

sub list-paths

sub list-paths(IO() $path, Bool :$d, Bool :$f = True, Bool :$r = True, Bool :$dot --> Array[IO::Path])

Returns an Array of IO::Path of all paths under $path.

If :$d is True directories will be returned.

If $f is set to False then files will not be returned.

If $r is set to False it will not recurse into directories.

If $dot is True then the current directory may be included in the return results.

sub copy-paths

sub copy-paths(IO() $from-path, IO() $to-path, Bool :$d, Bool :$f = True, Bool :$r = True, Bool :$dot --> Array[IO::Path])

Copy all paths under $from-path to a directory $to-path and returns an Array of IO::Path of the successfully copied files (their new locations).

If :$d is True directories without files may be created.

If $f is set to False then files will not be copied.

If $r is False it will not recurse into directories.

If $dot is True then the current directory may be copied.

sub move-paths

sub move-paths(IO() $from-path!, IO() $to-path, Bool :$d, Bool :$f = True, Bool :$r = True, Bool :$dot --> Array[IO::Path])

Move all paths under $from-path to a directory $to-path and returns an Array of IO::Path of the successfully moved files (their new locations).

If :$d is False directories without files won't be created.

If $f is set to False then files will not be moved.

If $r is False it will not recurse into directories. If $dot is True then the current directory may be moved.

sub delete-paths

sub delete-paths(IO() $path!, Bool :$d, Bool :$f = True, Bool :$r = True, Bool :$dot --> Array[IO::Path])

Delete all paths under $path and returns an Array of IO::Path of what was deleted.

If :$d is False directories without files won't be deleted.

If $f is set to False then files will not be deleted.

If $r is False it will not recurse into directories.

If $dot is True then the current directory may be deleted.

sub file-lock-protect

sub lock-file-protect(IO() $path, &code, Bool :$shared = False)

Provides an interface similar to Lock.protect that is backed by a file lock on $path instead of a semaphore. Its purpose is to help keep multiple instances of zef from trying to edit the e.g. p6c/cpan ecosystem index at the same time (although how well it serves that purpose in practice is unknown).

sub which

our sub which(Str $name --> Array[IO::Path])

Search the current env PATH, returning an Array of IO::Path with paths that contain a matching file $name. This is used for determining if a dependency such as curl:from<bin> is installed.