view release on metacpan or  search on metacpan

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

=head1 NAME

AnyEvent::Filesys::Watcher::FSEvents - MacOS file system watcher

=head1 SYNOPSIS

    $watcher = AnyEvent::Filesys::Watcher::FSEvents->new(
        directories => ['lib', 't'],
        callback => sub { warn "you're working too much"},
    );

    # This has the same effect as:

    $watcher = AnyEvent::Filesys::Watcher->new(
        backend => 'FSEvents',
        directories => ['lib', 't'],
        callback => sub { warn "you're working too much"},
    );

=head1 DESCRIPTION

This is the Mac OS backend for L<AnyEvent::Filesys::Watcher>.  It uses
L<Mac::FSEvents> as the underlying implementation.

=head1 INSTALLATION

At the time of this writing, the version on CPAN is 0.14 and will most likely
fail to build.  It fails with "Could not parse version string!".

If you run into this problem, try to use the
L<fork|https://github.com/skaji/Mac-FSEvents> instead. See
L<https://github.com/glohr/AnyEvent-Filesys-Watcher/#installation> for more
information.

=head1 CONSTRUCTOR

You should normally call the
L<constructor of the base class|AnyEvent::Filesys::Watch/"CONSTRUCTOR"> that
will pick the optimal backend for the current platform.

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!

B<OPTIONS> is a hash of named options (all other options are passed verbatim
to the constructor of L<Mac::FSEvents>):

=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::Events>.

One of the options "callback" or "raw_events" (see below) are required.

=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 latency for L<Mac::FSEvents>.  The latency is the time used by
fsevents daemon to merge multiple events into fewer ones.  A higher value may
reduce the number of events triggered.

Optional. The default is 0.1 s.

=item B<filter FILTER>

B<FILTER> should either be a regular expression or a code reference.  If this
is a regular expression, only (absolute) file names matching that regular
expressions can cause an event.

If B<FILTER> is a code reference, the subrouting receives the absolute file
name as an argument and should return a truthy value for all files that
should cause an event.

Optional. By default, all events are passed through.