view release on metacpan or  search on metacpan

lib/AnyEvent/Filesys/Watcher.pod  view on Meta::CPAN

=head1 NAME

AnyEvent::Filesys::Watcher - Watch file system for changes

=head1 SYNOPSIS

    use AnyEvent::Filesys::Watcher;

    $watcher = AnyEvent::Filesys::Watcher->new(
        directories => ['src', 'deps'],
        interval => 2.0,
        filter => sub { shift !~ /\.(swp|tmp)$/ },
        callback => sub {
        my (@events) = @_;
            # Process.
        },
    );

=head1 DESCRIPTION

This module is very similar to B<AnyEvent::Filesys::Notify>.  The main
difference is that it is not based on L<Moo> and has therefore has less
dependencies.

See L</"DIFFERENCES TO AnyEvent::Filesys::Notify"> for other differences.

=head1 CONSTRUCTORS

The following constructors are available:

=over 4

=item B<new(OPTIONS)>

Creates a new B<AnyEvent::Filesys::Watcher>.  The constructor may throw an
exception in case of an error!

In fact, it createss an instance of one of the subclasses
L<AnyEvent::Filesys::Watcher::Fallback> (all platforms),
L<AnyEvent::Filesys::Watcher::FSEvents> (macOS),
L<AnyEvent::Filesys::Watcher::INotify2> (Linux),
L<AnyEvent::Filesys::Watcher::KQueue> (BSD/macOS),
L<AnyEvent::Filesys::Watcher::ReadDirectoryChanges> (MS-DOS aka Windows) that
all inherit from this module.

If the instantiation of the subclass fails, an instance of
L<AnyEvent::Filesys::Watcher::Fallback> is returned unless a specific backend
was explicitely requested with the constructor argument "backend" (see below).

B<OPTIONS> is a hash of named options:

=over 8

=item B<directories DIRECTORIES>

B<DIRECTORIES> is a reference to an array of directories to monitor. A single
directory can also be passed as a scalar.

Optional. The default is the base directory, see "base_dir" below.

=item B<dirs DIRECTORIES>

This is an alias for the option "directories".

=item B<base_dir BASE_DIRECTORY>

Relative path names for the "directories" option are resolved relative to
B<BASE_DIRECTORY>.

The default is the current working directory at the time that the
object was instantiated.

=item B<callback CALLBACK>

A code reference that is called, when a modification to the monitored
directories is deteced. The callback is passed a list of
L<AnyEvent::Filesys::Watcher::Event>s.

This option is mandatory.

=item B<cb CALLBACK>

This is an alias for the parameter B<callback>.

This argument is required if the argument B<callback> has not been given.

=item B<interval SECONDS>

Specifies the time in fractional seconds between file system checks
for the L<AnyEvent::Filesys::Watcher::Fallback> implementation.

Specifies the latency for L<Mac::FSEvents> for the
L<AnyEvent::Filesys::Watcher::FSEvents> implementation.

Ignored for all other backends.