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

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.

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.

print

Which events to log. Unless parameter logger is specified, events are printed to STDOUT or STDERR. 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.