1File::ChangeNotify::WatUcsheerr(C3o)ntributed Perl DocumFeinltea:t:iCohnangeNotify::Watcher(3)
2
6 File::ChangeNotify::Watcher - Role consumed by all watchers
7
9 version 0.31
10
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 if ( my @events = $watcher->new_events ) { ... }
21 # blocking
23 while ( my @events = $watcher->wait_for_events ) { ... }
24
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 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 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 You can block while waiting for events or do a non-blocking call asking
42 for any new events since the last call (or since the watcher was
43 instantiated). Different watchers will implement blocking in different
44 ways, and the Default watcher just does a sleep loop.
45
47 File::ChangeNotify::Watcher::Subclass->new(...)
48 This method creates a new watcher. It accepts the following arguments:
49 · directories => $path
51 · directories => \@paths
53 This argument is required. It can be either one or many paths which
55 should be watched for changes.
56 · filter => qr/.../
58 This is an optional regular expression that will be used to check
60 if a file is of interest. This filter is only applied to files.
61 By default, all files are included.
63 · exclude => [...]
65 An optional arrayref of paths to exclude. This arrayref can contain
67 plain strings, regular expressions, or subroutine references. If
68 you provide a string it should contain the complete path to be
69 excluded.
70 If you provide a sub, it should return a true value for paths to be
72 excluded e.g. "exclude => [ sub { -e && ! -r } ],". The path will
73 be passed as the first argument to the subroutine as well as in a
74 localized $_.
75 The paths can be either directories or specific files. If the
77 exclusion matches a directory, all of its files and subdirectories
78 are ignored.
79 · modify_includes_file_attributes
81 This can either be a boolean or an arrayref.
83 If it is an arrayref then it should contain paths for which you
85 want information about changes to the file's attributes. This
86 arrayref can contain plain strings, regular expressions, or
87 subroutine references. If you provide a string it should contain
88 the complete path to be excluded.
89 When this matches a file, then modify events for that file will
91 include information about the file's before and after permissions
92 and ownership when these change.
93 See the File::ChangeNotify::Event documentation for details on what
95 this looks like.
96 · modify_includes_content
98 This can either be a boolean or an arrayref.
100 If it is an arrayref then it should contain paths for which you
102 want to see past and current content for a file when it is
103 modified. This arrayref can contain plain strings, regular
104 expressions, or subroutine references. If you provide a string it
105 should contain the complete path to be excluded.
106 When this matches a file, then modify events for that file will
108 include information about the file's before and after content when
109 it changes.
110 See the File::ChangeNotify::Event documentation for details on what
112 this looks like.
113 · follow_symlinks => $bool
115 By default, symlinks are ignored. Set this to true to follow them.
117 If this symlinks are being followed, symlinks to files and
119 directories will be followed. Directories will be watched, and
120 changes for directories and files reported.
121 · sleep_interval => $number
123 For watchers which call "sleep" to implement the
125 "$watcher->wait_for_events" method, this argument controls how long
126 it sleeps for. The value is a number in seconds.
127 The default is 2 seconds.
129 · event_class => $class
131 This can be used to change the class used to report events. By
133 default, this is File::ChangeNotify::Event.
134 $watcher->wait_for_events
136 This method causes the watcher to block until it sees interesting
137 events, and then return them as a list.
138 Some watcher subclasses may implement blocking as a sleep loop, while
140 others may actually block.
141 $watcher->new_events
143 This method returns a list of any interesting events seen since the
144 last time the watcher checked.
145 $watcher->sees_all_events
147 If this is true, the watcher will report on all events.
148 Some watchers, like the Default subclass, are not smart enough to track
150 things like a file being created and then immediately deleted, and can
151 only detect changes between snapshots of the file system.
152 Other watchers, like the Inotify subclass, see all events that happen
154 and report on them.
155
157 Bugs may be submitted at
158 <http://rt.cpan.org/Public/Dist/Display.html?Name=File-ChangeNotify> or
159 via email to bug-file-changenotify@rt.cpan.org <mailto:bug-file-
160 changenotify@rt.cpan.org>.
161 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
163
165 The source code repository for File-ChangeNotify can be found at
166 <https://github.com/houseabsolute/File-ChangeNotify>.
167
169 Dave Rolsky <autarch@urth.org>
170
172 This software is Copyright (c) 2009 - 2019 by Dave Rolsky.
173 This is free software, licensed under:
175 The Artistic License 2.0 (GPL Compatible)
177 The full text of the license can be found in the LICENSE file included
179 with this distribution.
180perl v5.32.0 2020-07-28 File::ChangeNotify::Watcher(3)