NAME

File::Hotfolder - recursive watch directory for new or modified files

SYNOPSIS

    use File::Hotfolder;

    # object interface
    File::Hotfolder->new(
        watch    => '/some/directory',  # which directory to watch
        callback => sub {               # what to do with each new/modified file
            my $path = shift;
            ...
        },
        fork     => 0,                  # fork callback
        delete   => 1,                  # delete each file if callback returns true
        filter   => qr/\.json$/,        # only watch selected files
        print    => WATCH_DIR           # show which directories are watched
                    | HOTFOLDER_ERROR,  # show all errors (CATCH_ERROR | WATCH_ERROR)
        catch    => sub {               # catch callback errors
            my ($path, $error) = @_;
            ...
        },
        event_mask => IN_CLOSE          # filter event only to those of interest
    )->loop;

    # function interface
    watch( '/some/directory', callback => sub { say shift } )->loop;

    # watch a given directory and delete all new or modified files
    watch( $ARGV[0] // '.', delete  => 1, print => DELETE_FILE )->loop;

    # watch directory, delete all new/modified non-txt files, print all files
    watch( '/some/directory',
        callback => sub { $_[0] !~ /\.txt$/ },
        delete  => 1,
        print   => DELETE_FILE | KEEP_FILE
    );
    
    # wait for events with AnyEvent
    File::HotFolder->new( ... )->anyevent;
    AnyEvent->condvar->recv;

DESCRIPTION

This module uses Linux::Inotify2 to recursively watch a directory for new or modified files. A callback is called on each file with its path.

Deletions and new subdirectories are not reported but new subdirectories will be watched as well.

CONFIGURATION

watch

Base directory to watch. The WATCH_DIR event is logged for each watched (sub)directory and the UNWATCH_DIR event if directories are deleted. The WATCH_ERROR event is logged if watching a directory failed and if the watch queue overflowed.

callback

Callback for each new or modified file. The callback is not called during a write but after a file has been closed. The FOUND_FILE event is logged before executing the callback.

delete

Delete the modified file if a callback returned a true value (disabled by default). A DELETE_FILE will be logged after deletion or a KEEP_FILE event otherwise.

event_mask

React only to those event satisfying the mask. Can be any mask built of the following Linux::Inotify2 event flags: IN_CREATE, IN_CLOSE_WRITE, IN_MOVE, IN_DELETE, IN_DELETE_SELF, IN_MOVE_SELF.

Defaults to IN_CLOSE_WRITE | IN_MOVED_TO.

fullname

Return absolute path names. By default pathes are relative to the base directory given with option watch.

filter

Filter file pathes with regular expression or code reference before passing to callback. Set to ignore all hidden files (starting with a dot) by default. Use 0 to disable.

filter_dir

Filter directory names with regular expression before watching. Set to ignore hidden directories (starting with a dot) by default. Use 0 to disable.

fork

Execute callback in a child process by forking if possible. Logging also takes place in the child process.

print

Log events to STDOUT and STDERR unless an explicit logger is specified.

This parameter expects a value with event types. Possible event types are exported as constants WATCH_DIR, UNWATCH_DIR, FOUND_FILE, DELETE_FILE, KEEP_FILE, CATCH_ERROR, and WATCH_ERROR. The constant HOTFOLDER_ERROR combines CATCH_ERROR and WATCH_ERROR and the constant HOTFOLDER_ALL combines all event types.

logger

Where to log events to. If given a code reference, the code is called with three named parameters:

    logger => sub { # event => $event, path => $path, message => $message
        my (%args) = @_;
        ...
    },

If given an object instance a logging method is created and called at the object's log method with argument level and message as expected by Log::Dispatch:

    logger => Log::Dispatch->new( ... ),

The level is set to error for HOTFOLDER_ERROR events and info for other events.

catch

Error callback for failing callbacks (event CATCH_ERROR). Disabled by default, so a dying callback will terminate the program.

scan

First call the callback for all existing files. This does not guarantee that found files have been closed.

METHODS

loop

Watch with a manual event loop. This method never returns.

anyevent

Watch with AnyEvent. Returns a new AnyEvent watch.

inotify

Returns the internal Linux::Inotify2 object. Future versions of this module may use another notify module (Win32::ChangeNotify, Mac::FSEvents, Filesys::Notify::KQueue...), so this method may return undef.

SEE ALSO

• File::ChangeNotify, Filesys::Notify::Simple

• AnyEvent

COPYRIGHT AND LICENSE

Copyright Jakob Voss, 2015-

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.