/ 
AnyEvent-Filesys-Watcher-v0.1.1
/ AnyEvent::Filesys::Watcher

NAME

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

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.
    },
);

DESCRIPTION

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

See "DIFFERENCES TO AnyEvent::Filesys::Notify" for other differences.

CONSTRUCTORS

The following constructors are available:

new(OPTIONS)

Creates a new 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 AnyEvent::Filesys::Watcher::Fallback (all platforms), AnyEvent::Filesys::Watcher::FSEvents (macOS), AnyEvent::Filesys::Watcher::INotify2 (Linux), AnyEvent::Filesys::Watcher::KQueue (BSD/macOS), AnyEvent::Filesys::Watcher::ReadDirectoryChanges (MS-DOS aka Windows) that all inherit from this module.

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

OPTIONS is a hash of named options:

directories DIRECTORIES

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.

dirs DIRECTORIES

This is an alias for the option "directories".

base_dir BASE_DIRECTORY

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

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

callback CALLBACK

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

This option is mandatory.

cb CALLBACK

This is an alias for the parameter callback.

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

interval SECONDS

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

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

Ignored for all other backends.

Optional. The default is backend-specific.

filter FILTER

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 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.

raw_events CALLBACK

Allows you to subscribe to the raw events returned by the os-specific backend. The CALLBACK gets invoked with a list of these backend-specific options and should return a list of backend-specific options. Did you read this? You have to return a list of events.

You can use this option if you are interested in the original events from your backend or if you want to filter these events before being processed.

You can use both the option "callback" and "raw_events" but the filter specified with the "filter" option is, of course, not applied to the raw events because their exact structure is backend-specific.

Optional. Note that the option "callback" is still mandatory, even if you have passed a callback to "raw_options". Some backends require post-processing of events and they have to be instances of AnyEvent::Filesys::Watcher::Event.

backend BACKEND

Force the use of the specified backend. The backend is assumed to have the "AnyEvent::Filesys::Watcher" prefix, but you can force a fully qualified name by prefixing it with a plus.

Optional. The default is os-dependent: For Linux it is AnyEvent::Filesys::Watcher::Inotify2, for Mac OS it is AnyEvent::Filesys::Watcher::FSEvents, for BSD systems it is AnyEvent::Filesys::Watcher::KQueue, for MS-DOS it is AnyEvent::Filesys::Watcher::ReadDirectoryChhanges and for all other systems it is AnyEvent::Filesys::Watcher::Fallback.

METHODS

The public API consists of the following methods:

directories

Getter for the array reference of directories that get monitored.

callback [CALLBACK]

Getter/setter for the callback.

interval

Getter for the interval between polls.

filter [FILTER]

Getter/setter for the filter.

INSTALLATION

You should install one of the helper module that provides the binding for the operating system's filesystem watch functionality:

Linux

Install Linux::Inotify2:

$ cpanm Linux::Inotify2

Mac OS

Install Mac::FSEvents:

$ cpanm Mac::FSEvents

Versions before 0.20 do not build on recent macOS instances.

BSD and macOS

Install IO::KQueue and BSD::Resource

$ cpanm IO::KQueue BSD::Resource

This would also work for Mac OS but you have little reason to prefer IO::KQueue over Mac::FSEvents unless you are a developer or just curious.

MS-DOS ("Windows")

Install Filesys::Notify::Win32::ReadDirectoryChanges.

This backend causes spurious errors. If that happens, please use the fallback backend.

USAGE RECOMMENDATIONS

Different platforms have different notions about file system changes and how to report them. This module tries to remove these differences and always report the same events for a certain file type change. The test suite tests this behaviour but still you should not rely on it.

A robust implementation using this module should follow two rules:

Do not expect events to come in a certain order.
Treat the events "modified" and "created" equally as "existing file has changed"

DIFFERENCES TO AnyEvent::Filesys::Notify

If you specify a subroutine as a filter, that subroutine receives events as arguments, not paths.
The constructor argument "no_external" is ignored.
There is no method "no_external()".
Methods and named arguments are "directories" and not "dirs".
Methods and named arguments are "callback" and not "cb".
The named argument "skip_subdirs" is not supported.
The named argument "parse_events" is ignored. Events are parsed by the backend, if possible, otherwise the file system is scanned.
None of the Moose methods like "does()" are implemented.
No type checking is done on arguments.

BUGS

Please report bugs to the issue tracker at GitHub.

AUTHOR

AnyEvent::Filesys::Watcher was written by Guido Flohr.

SEE ALSO

AnyEvent::Filesys::Watcher::Event, AnyEvent::Filesys::Watcher::Fallback, AnyEvent::Filesys::Watcher::FSEvents, AnyEvent::Filesys::Watcher::INotify2, AnyEvent::Filesys::Watcher::KQueue, AnyEvent::Filesys::Watcher::ReadDirectoryChanges, Linux::Inotify2, Mac::FSEvents, IO::KQueue, BSD::Resource, AnyEvent::Filesys::Notify, perl(1)