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.31
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       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

METHODS

47   File::ChangeNotify::Watcher::Subclass->new(...)
48       This method creates a new watcher. It accepts the following arguments:
49
50       •   directories => $path
51
52       •   directories => \@paths
53
54           This argument is required. It can be either one or many paths which
55           should be watched for changes.
56
57       •   filter => qr/.../
58
59           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
62           By default, all files are included.
63
64       •   exclude => [...]
65
66           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
71           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
76           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
80       •   modify_includes_file_attributes
81
82           This can either be a boolean or an arrayref.
83
84           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
90           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
94           See the File::ChangeNotify::Event documentation for details on what
95           this looks like.
96
97       •   modify_includes_content
98
99           This can either be a boolean or an arrayref.
100
101           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
107           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
111           See the File::ChangeNotify::Event documentation for details on what
112           this looks like.
113
114       •   follow_symlinks => $bool
115
116           By default, symlinks are ignored. Set this to true to follow them.
117
118           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
122       •   sleep_interval => $number
123
124           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
128           The default is 2 seconds.
129
130       •   event_class => $class
131
132           This can be used to change the class used to report events. By
133           default, this is File::ChangeNotify::Event.
134
135   $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
139       Some watcher subclasses may implement blocking as a sleep loop, while
140       others may actually block.
141
142   $watcher->new_events
143       This method returns a list of any interesting events seen since the
144       last time the watcher checked.
145
146   $watcher->sees_all_events
147       If this is true, the watcher will report on all events.
148
149       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
153       Other watchers, like the Inotify subclass, see all events that happen
154       and report on them.
155

SUPPORT

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
162       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
163

SOURCE

165       The source code repository for File-ChangeNotify can be found at
166       <https://github.com/houseabsolute/File-ChangeNotify>.
167

AUTHOR

169       Dave Rolsky <autarch@urth.org>
170
172       This software is Copyright (c) 2009 - 2019 by Dave Rolsky.
173
174       This is free software, licensed under:
175
176         The Artistic License 2.0 (GPL Compatible)
177
178       The full text of the license can be found in the LICENSE file included
179       with this distribution.
180
181
182
183perl v5.32.1                      2021-01-27    File::ChangeNotify::Watcher(3)
Impressum