NAME

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

STATUS

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.