File::ChangeNotify::WaUserrContributed Perl DocuFile::ChangeNotify::Watcher(3)NAMEFile::ChangeNotify::Watcher - Base class for all watchers
VERSION
version 0.16
SYNOPSIS
my $watcher =
File::ChangeNotify->instantiate_watcher
( directories => [ '/my/path', '/my/other' ],
filter => qr/\.(?:pm|conf|yml)$/,
exclude => ['t', 'root', qr(/(?!\.)[^/]+$)],
);
if ( my @events = $watcher->new_events() ) { ... }
# blocking
while ( my @events = $watcher->wait_for_events() ) { ... }
DESCRIPTION
A "File::ChangeNotify::Watcher" class monitors a directory for changes
made to any file. You can provide a regular expression to filter out
files you are not interested in. It handles the addition of new
subdirectories by adding them to the watch list.
Note that the actual granularity of what each watcher subclass reports
may vary across subclasses. Implementations that hook into some sort of
kernel event interface (Inotify, for example) have much better
knowledge of exactly what changes are happening than one implemented
purely in userspace code (like the Default subclass).
By default, events are returned in the form File::ChangeNotify::Event
objects, but this can be overridden by providing an "event_class"
attribute to the constructor.
The watcher can operate in a blocking/callback style, or you can simply
ask it for a list of new events as needed.
METHODS
File::ChangeNotify::Watcher::Subclass->new(...)
This method creates a new watcher. It accepts the following arguments:
· directories => $path
· directories => \@paths
This argument is required. It can be either one or many paths which
should be watched for changes.
· filter => qr/.../
This is an optional regular expression that will be used to check
if a file is of interest. This filter is only applied to files.
By default, all files are included.
· exclude => [...]
An optional list of paths to exclude. This list can contain either
plain strings or regular expressions. If you provide a string it
should contain the complete path to be excluded.
The paths can be either directories or specific files. If the
exclusion matches a directory, all of its files and subdirectories
are ignored.
· follow_symlinks => $bool
By default, symlinks are ignored. Set this to true to follow them.
If this symlinks are being followed, symlinks to files and
directories will be followed. Directories will be watched, and
changes for directories and files reported.
· sleep_interval => $number
For watchers which call "sleep" to implement the
"$watcher->wait_for_events()" method, this argument controls how
long it sleeps for. The value is a number in seconds.
The default is 2 seconds.
· event_class => $class
This can be used to change the class used to report events. By
default, this is File::ChangeNotify::Event.
$watcher->wait_for_events()
This method causes the watcher to block until it sees interesting
events, and then return them as a list.
Some watcher subclasses may implement blocking as a sleep loop, while
others may actually block.
$watcher->new_events()
This method returns a list of any interesting events seen since the
last time the watcher checked.
$watcher->sees_all_events()
If this is true, the watcher will report on all events.
Some watchers, like the Default subclass, are not smart enough to track
things like a file being created and then immediately deleted, and can
only detect changes between snapshots of the file system.
Other watchers, like the Inotify subclass, see all events that happen
and report on them.
AUTHOR
Dave Rolsky <autarch@urth.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2010 by Dave Rolsky.
This is free software, licensed under:
The Artistic License 2.0
perl v5.14.1 2010-07-12 File::ChangeNotify::Watcher(3)
