NAME

       File::ChangeNotify::Watcher - Role consumed by all watchers

VERSION

       version 0.31

SYNOPSIS

           my $watcher =
               File::ChangeNotify->instantiate_watcher
                   ( directories => [ '/my/path', '/my/other' ],
                     filter      => qr/\.(?:pm|conf|yml)$/,
                     exclude     => ['t', 'root', qr(/(?!\.)[^/]+$),
                                     sub { -e && ! -r }],
                   );

           if ( my @events = $watcher->new_events ) { ... }

           # blocking
           while ( my @events = $watcher->wait_for_events ) { ... }

DESCRIPTION

       A "File::ChangeNotify::Watcher" monitors a directory for changes made to any file. You can
       provide a regular expression to filter out files you are not interested in. It handles the
       addition of new subdirectories by adding them to the watch list.

       Note that the actual granularity of what each watcher class reports may vary.
       Implementations that hook into some sort of kernel event interface (Inotify, for example)
       have much better knowledge of exactly what changes are happening than one implemented
       purely in userspace code (like the Default class).

       By default, events are returned in the form of File::ChangeNotify::Event objects, but this
       can be overridden by providing an "event_class" attribute to the constructor.

       You can block while waiting for events or do a non-blocking call asking for any new events
       since the last call (or since the watcher was instantiated). Different watchers will
       implement blocking in different ways, and the Default watcher just does a sleep loop.

METHODS

   File::ChangeNotify::Watcher::Subclass->new(...)
       This method creates a new watcher. It accepts the following arguments:

       •   directories => $path

       •   directories => \@paths

           This argument is required. It can be either one or many paths which should be watched
           for changes.

       •   filter => qr/.../

           This is an optional regular expression that will be used to check if a file is of
           interest. This filter is only applied to files.

           By default, all files are included.

       •   exclude => [...]

           An optional arrayref of paths to exclude. This arrayref can contain plain strings,
           regular expressions, or subroutine references. If you provide a string it should
           contain the complete path to be excluded.

           If you provide a sub, it should return a true value for paths to be excluded e.g.
           "exclude => [ sub { -e && ! -r } ],". The path will be passed as the first argument to
           the subroutine as well as in a localized $_.

           The paths can be either directories or specific files. If the exclusion matches a
           directory, all of its files and subdirectories are ignored.

       •   modify_includes_file_attributes

           This can either be a boolean or an arrayref.

           If it is an arrayref then it should contain paths for which you want information about
           changes to the file's attributes. This arrayref can contain plain strings, regular
           expressions, or subroutine references. If you provide a string it should contain the
           complete path to be excluded.

           When this matches a file, then modify events for that file will include information
           about the file's before and after permissions and ownership when these change.

           See the File::ChangeNotify::Event documentation for details on what this looks like.

       •   modify_includes_content

           This can either be a boolean or an arrayref.

           If it is an arrayref then it should contain paths for which you want to see past and
           current content for a file when it is modified. This arrayref can contain plain
           strings, regular expressions, or subroutine references. If you provide a string it
           should contain the complete path to be excluded.

           When this matches a file, then modify events for that file will include information
           about the file's before and after content when it changes.

           See the File::ChangeNotify::Event documentation for details on what this looks like.

       •   follow_symlinks => $bool

           By default, symlinks are ignored. Set this to true to follow them.

           If this symlinks are being followed, symlinks to files and directories will be
           followed. Directories will be watched, and changes for directories and files reported.

       •   sleep_interval => $number

           For watchers which call "sleep" to implement the "$watcher->wait_for_events" method,
           this argument controls how long it sleeps for. The value is a number in seconds.

           The default is 2 seconds.

       •   event_class => $class

           This can be used to change the class used to report events. By default, this is
           File::ChangeNotify::Event.

   $watcher->wait_for_events
       This method causes the watcher to block until it sees interesting events, and then return
       them as a list.

       Some watcher subclasses may implement blocking as a sleep loop, while others may actually
       block.

   $watcher->new_events
       This method returns a list of any interesting events seen since the last time the watcher
       checked.

   $watcher->sees_all_events
       If this is true, the watcher will report on all events.

       Some watchers, like the Default subclass, are not smart enough to track things like a file
       being created and then immediately deleted, and can only detect changes between snapshots
       of the file system.

       Other watchers, like the Inotify subclass, see all events that happen and report on them.

SUPPORT

       Bugs may be submitted at
       <http://rt.cpan.org/Public/Dist/Display.html?Name=File-ChangeNotify> or via email to
       bug-file-changenotify@rt.cpan.org <mailto:bug-file-changenotify@rt.cpan.org>.

       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".

SOURCE

       The source code repository for File-ChangeNotify can be found at
       <https://github.com/houseabsolute/File-ChangeNotify>.

AUTHOR

       Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2009 - 2019 by Dave Rolsky.

       This is free software, licensed under:

         The Artistic License 2.0 (GPL Compatible)

       The full text of the license can be found in the LICENSE file included with this
       distribution.