unit package App::Lorea::Watcher:ver<0.2.2>;



head

App::Lorea::Watcher - General use file recursive file watching subs


code

=begin code

use App::Lorea::Watcher;

my $supply = $path.&watch-recursive(
    debounce => 0.5,
    exclude  => rx{ '~' $ }, # Ignore files ending in ~
);

whenever $supply { ... }

=end code


This module exports a single subroutine to make it easier to recursively
watch a directory for file changes. It is currently bundled in with
App::Lorea, but it does not depend on it for proper use.


=begin code
sub watch-recursive(
    $root,        # The root from where recursion will start
    :$exclude,    # A matcher to exclude
    :$debounce,   # Seconds to wait before emitting the same path
) returns Supply
=end code


Returns a live Supply of IO::Notification::Change with changes to
any file or directory under C<$root> recursively. This includes any
changes to the direct contents of C<$root>. C<$root> can be anything
on which C<.IO> can be called.


An optional C<$debounce> numeric parameter may be provided. If so, the
same path will not be emitted until at least that number of seconds have
passed, or a large enough number of events have been seen. This number
can be set with the C<$cache-size> parameter.


If provided, C<$exclude> is matched against the result of calling
C<App::Lorea::Watcher::normalise> on the path relative to C<$root>. Any
matching paths will I<not> be sent through the Supply.


Based on https://github.com/zoffixznet/perl6-Ticket-Trakr



# Copied from relevant bits of Hash::LRU, to avoid dependency
my class Cache is Hash {
    has int $!size is built = 20;
    has str @!keys;

    method AT-KEY ( ::?CLASS:D: \key ) is raw is hidden-from-backtrace {
        self!SEEN-KEY(key) if self.EXISTS-KEY(key);
        nextsame
    }

    method ASSIGN-KEY ( ::?CLASS:D: \key, \value ) is hidden-from-backtrace {
        self!SEEN-KEY(key);
        nextsame
    }

    method BIND-KEY ( ::?CLASS:D: \key, \value ) is hidden-from-backtrace {
        self!SEEN-KEY(key);
        nextsame
    }

    method STORE ( \to_store ) is hidden-from-backtrace {
        callsame;
        self!INIT-KEYS;
        self!SEEN-KEY($_) for self.keys;
        self
    }

    method !INIT-KEYS ( --> Nil ) { @!keys = () }

    method !SEEN-KEY ( Str(Any) $key --> Nil ) {
        if @!keys.elems -> int $elems {
            my int $i = -1;
            Nil while ++$i < $elems && @!keys.AT-POS($i) ne $key;

            if $i < $elems {
                @!keys.splice($i,1);
            }
            elsif $elems == $!size {
                self.DELETE-KEY(@!keys.pop);
            }
        }

        @!keys.unshift($key);
    }
}

sub watch-recursive(
         $root,             # The root from where recursion will start
        :$exclude,          # A matcher to exclude
        :$debounce,         # Seconds to wait before emitting the same path
    Int :$cache-size = 100, # Maximum number of items to cache for debouncing
    --> Supply
) is export {
    my $cache = Cache.new( size => $cache-size );
    my $supplier = Supplier.new;

    start react {
        my sub watch-it($p) {
            CATCH {
                default {
                    say "ERROR: { .^name }";
                }
            }

            whenever IO::Notification.watch-path($p) {
                my $path = .path;

                if .event ~~ FileRenamed && $path.IO.d {
                    .&watch-it for find-dirs $path, :$exclude;
                }

                next if .event !~~ FileChanged;
                next unless $path.IO.e;

                next if $exclude
                    && $path.&normalise($root) ~~ $exclude;

                if $debounce {
                    next if $cache{$path}
                        && now - $cache{$path} < $debounce;

                    $cache{$path} = now;
                }

                $supplier.emit: $_;
            }
        }

        .&watch-it for find-dirs ~$root, :$exclude;
    }

    $supplier.Supply;
}

# Normalise a path for matching. Paths will be relative to C<$root>
# (or to C<$*CWD> if none is given). Directories are guaranteed to have
# a trailing '/'. Normalised paths do not have a leading './'.
our sub normalise ( $path, $root = $*CWD ) is export(:normalise) {
    with $path.IO {
        my $name = .relative($root);
        $name ~= '/' if .d && !.ends-with('/');
        return $name;
    }
}

# Lazily returns a list of directories found recursively under the directory
# specified as C<$root>. C<$root> can be anything on which C<.IO> can be called.
#
# If provided, C<$exclude> is matched against the result of calling
# C<App::Lorea::Watcher::normalise> on the path relative to C<$root>.
my sub find-dirs (
    $root,     # The root from where recursion will start
    :$exclude, # A matcher to exclude directories
 ) {
    my %seen;
    my @stack = $root.IO;
    gather while @stack {
        with @stack.pop -> $path {
            CATCH {
                when X::IO::Dir { note "Could not read $path, skipping..." }
                default {
                    say "UNHANDLED ERROR: { .^name }";
                }
            }

            next unless $path.d;
            next if %seen{$path}++;
            next if $exclude && $path.&normalise($root) ~~ $exclude;

            @stack.append: $path.dir;
            $path.take;
        }
    }
}



This library is free software; you can redistribute it and/or modify it
under the Artistic License 2.0.


root

README

Command

React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


Watcher

NAME

SYNOPSIS

DESCRIPTION

SUBROUTINES

watch-recursive

AUTHOR

COPYRIGHT AND LICENSE

App::Lorea v0.2.2

Authors

License

Dependencies

Test Dependencies

Provides

Documentation