=head1 NAME

UniEvent::FsEvent - cross-platform file/dir monitoring



=head1 SYNOPSIS

    use UniEvent::FsEvent; # imports constants

    my $h = UniEvent::FsEvent->new;
    $h->start("/tmp/", RECURSIVE, sub {
        my ($handle, $filename, $events, $error_code) = @_;
            if ($events & RENAME) {
            say "file $filename has been renamed";
        }
    });
    UE::Loop->default->run;



=head1 DESCRIPTION

The C<FsEvent> is useful for monitoring individual file events , e.g.
when file is renamed, created or when its content was changed.
It works on major operational systems, including Windows; however
the order of events might be system dependent.
This handle uses the best backend for the job on each platform.

The C<UniEvent::FsEvent> is inherited from L<UniEvent::Handle>.



=head1 METHODS

All methods of L<UniEvent::Handle> also apply.

=head2 create($path, $flags, $callback, [$loop = default])

    my $handle = UniEvent::FsEvent->create("my/file", 0, sub { say "hi" });

Creates and starts an fs event handle. Alias for C<new($loop)> + C<start($path, $flags, $callback)>.


=head2 new([$loop = default])

Constructs new FsEvent handle and binds it to the specified event loop


=head2 start($path, [$flags], [$callback])

Starts monitoring file system events on the specified C<$path>,
i.e. makes it active for the next even loop iteration. The C<$path>
can point to file as well as to directory.

The C<$flags> is a bitmask of (in UE::FsEvent::*):

=over

=item RECURSIVE

Watch for changes recursively (might not be available on all operating systems)

=back

L<May return error|UniEvent/"OPTIONAL ERRORS">


=head2 stop()

Stops monitoring file system events.

L<May return error|UniEvent/"OPTIONAL ERRORS">


=head2 callback($sub)

=head2 event()

Callback signature:

    my ($handle, $filename, $events, $error) = @_;

Where C<$handle> is the FsEvent handle object itself.

C<$filename> is path to the triggered file. If the handle was started with a directory the filename parameter will be a relative path
to a file contained in the directory.

The C<$events> parameter is an ORed mask of these flags (in UE::FsEvent::*):

=over

=item RENAME

When file was moved

=item CHANGE

When file data (content) or metadata changes (e.g. C<mtime>).

=back

The C<$error> parameter will be an L<XS::ErrorCode> object if any.

See L<UniEvent/"EVENT CALLBACKS">


=head2 event_listener($delegate, [$weak])

Method C<on_fs_event> will be called.

See L<UniEvent/"EVENT LISTENER">


=head2 path()

Returns the currently monitored path.


=head1 CONSTANTS


=cut
