1File::ChangeNotify::WatUcsheerr(C3o)ntributed Perl DocumFeinltea:t:iCohnangeNotify::Watcher(3)
2
3
4

NAME

6       File::ChangeNotify::Watcher - Role consumed by all watchers
7

VERSION

9       version 0.29
10

SYNOPSIS

12           my $watcher =
13               File::ChangeNotify->instantiate_watcher
14                   ( directories => [ '/my/path', '/my/other' ],
15                     filter      => qr/\.(?:pm|conf|yml)$/,
16                     exclude     => ['t', 'root', qr(/(?!\.)[^/]+$),
17                                     sub { -e && ! -r }],
18                   );
19
20           if ( my @events = $watcher->new_events() ) { ... }
21
22           # blocking
23           while ( my @events = $watcher->wait_for_events() ) { ... }
24

DESCRIPTION

26       A "File::ChangeNotify::Watcher" monitors a directory for changes made
27       to any file. You can provide a regular expression to filter out files
28       you are not interested in. It handles the addition of new
29       subdirectories by adding them to the watch list.
30
31       Note that the actual granularity of what each watcher class reports may
32       vary. Implementations that hook into some sort of kernel event
33       interface (Inotify, for example) have much better knowledge of exactly
34       what changes are happening than one implemented purely in userspace
35       code (like the Default class).
36
37       By default, events are returned in the form of
38       File::ChangeNotify::Event objects, but this can be overridden by
39       providing an "event_class" attribute to the constructor.
40
41       The watcher can operate in a blocking/callback style, or you can simply
42       ask it for a list of new events as needed.
43

METHODS

45   File::ChangeNotify::Watcher::Subclass->new(...)
46       This method creates a new watcher. It accepts the following arguments:
47
48       ·   directories => $path
49
50       ·   directories => \@paths
51
52           This argument is required. It can be either one or many paths which
53           should be watched for changes.
54
55       ·   filter => qr/.../
56
57           This is an optional regular expression that will be used to check
58           if a file is of interest. This filter is only applied to files.
59
60           By default, all files are included.
61
62       ·   exclude => [...]
63
64           An optional list of paths to exclude. This list can contain plain
65           strings, regular expressions, or subroutine references. If you
66           provide a string it should contain the complete path to be
67           excluded.
68
69           If you provide a sub, it should return a true value for paths to be
70           excluded e.g. "exclude => [ sub { -e && ! -r } ],". The path will
71           be passed as the first argument to the subroutine as well as in a
72           localized $_.
73
74           The paths can be either directories or specific files. If the
75           exclusion matches a directory, all of its files and subdirectories
76           are ignored.
77
78       ·   follow_symlinks => $bool
79
80           By default, symlinks are ignored. Set this to true to follow them.
81
82           If this symlinks are being followed, symlinks to files and
83           directories will be followed. Directories will be watched, and
84           changes for directories and files reported.
85
86       ·   sleep_interval => $number
87
88           For watchers which call "sleep" to implement the
89           "$watcher->wait_for_events()" method, this argument controls how
90           long it sleeps for. The value is a number in seconds.
91
92           The default is 2 seconds.
93
94       ·   event_class => $class
95
96           This can be used to change the class used to report events. By
97           default, this is File::ChangeNotify::Event.
98
99   $watcher->wait_for_events()
100       This method causes the watcher to block until it sees interesting
101       events, and then return them as a list.
102
103       Some watcher subclasses may implement blocking as a sleep loop, while
104       others may actually block.
105
106   $watcher->new_events()
107       This method returns a list of any interesting events seen since the
108       last time the watcher checked.
109
110   $watcher->sees_all_events()
111       If this is true, the watcher will report on all events.
112
113       Some watchers, like the Default subclass, are not smart enough to track
114       things like a file being created and then immediately deleted, and can
115       only detect changes between snapshots of the file system.
116
117       Other watchers, like the Inotify subclass, see all events that happen
118       and report on them.
119

SUPPORT

121       Bugs may be submitted at
122       <http://rt.cpan.org/Public/Dist/Display.html?Name=File-ChangeNotify> or
123       via email to bug-file-changenotify@rt.cpan.org <mailto:bug-file-
124       changenotify@rt.cpan.org>.
125
126       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
127

SOURCE

129       The source code repository for File-ChangeNotify can be found at
130       <https://github.com/houseabsolute/File-ChangeNotify>.
131

AUTHOR

133       Dave Rolsky <autarch@urth.org>
134

136       This software is Copyright (c) 2009 - 2018 by Dave Rolsky.
137
138       This is free software, licensed under:
139
140         The Artistic License 2.0 (GPL Compatible)
141
142       The full text of the license can be found in the LICENSE file included
143       with this distribution.
144
145
146
147perl v5.28.0                      2018-09-25    File::ChangeNotify::Watcher(3)
Impressum