1NAME
2 File::Monitor - Monitor files and directories for changes.
3
4VERSION
5 This document describes File::Monitor version 1.00
6
7SYNOPSIS
8 use File::Monitor;
9
10 my $monitor = File::Monitor->new();
11
12 # Just watch
13 $monitor->watch('somefile.txt');
14
15 # Watch with callback
16 $monitor->watch('otherfile.txt', sub {
17 my ($name, $event, $change) = @_;
18 # Do stuff
19 });
20
21 # Watch a directory
22 $monitor->watch( {
23 name => 'somedir',
24 recurse => 1,
25 callback => {
26 files_created => sub {
27 my ($name, $event, $change) = @_;
28 # Do stuff
29 }
30 }
31 } );
32
33 # First scan just finds out about the monitored files. No changes
34 # will be reported.
35 $object->scan;
36
37 # Later perform a scan and gather any changes
38 my @changes = $object->scan;
39
40DESCRIPTION
41 This module provides a simple interface for monitoring one or more files
42 or directories and reporting any changes that are made to them.
43
44 It can
45
46 * monitor existing files for changes to any of the attributes returned
47 by the "stat" function
48
49 * monitor files that don't yet exist and notify you if they are
50 created
51
52 * notify when a monitored file is deleted
53
54 * notify when files are added or removed from a directory
55
56 Some possible applications include
57
58 * monitoring the configuration file(s) of a long running process so
59 they can be automatically re-read if they change
60
61 * implementing a 'drop box' directory that receives files to be
62 processed in some way
63
64 * automatically rebuilding a cached object that depends on a number of
65 files if any of those files changes
66
67 In order to monitor a single file create a new monitor object:
68
69 my $monitor = File::Monitor->new();
70
71 Add the file to it:
72
73 $monitor->watch( 'somefile.txt' );
74
75 And then call "scan" periodically to check for changes:
76
77 my @changes = $monitor->scan;
78
79 The first call to "scan" will never report any changes; it captures a
80 snapshot of the state of all monitored files and directories so that
81 subsequent calls to "scan" can report any changes.
82
83 Note that "File::Monitor" doesn't provide asynchronous notifications of
84 file changes; you have to call "scan" to learn if there have been any
85 changes.
86
87 To monitor multiple files call "watch" for each of them:
88
89 for my $file ( @files ) {
90 $monitor->watch( $file );
91 }
92
93 If there have been any changes "scan" will return a list of
94 File::Monitor::Delta objects.
95
96 my @changes = $monitor->scan;
97 for my $change (@changes) {
98 warn $change->name, " has changed\n";
99 }
100
101 Consult the documentation for File::Monitor::Delta for more information.
102
103 If you prefer you may register callbacks to be triggered when changes
104 occur.
105
106 # Gets called for all changes
107 $monitor->callback( sub {
108 my ($file_name, $event, $change) = @_;
109 warn "$file_name has changed\n";
110 } );
111
112 # Called when file size changes
113 $monitor->callback( size => sub {
114 my ($file_name, $event, $change) = @_;
115 warn "$file_name has changed size\n";
116 } );
117
118 See File::Monitor::Delta for more information about the various event
119 types for which callbacks may be registered.
120
121 You may register callbacks for a specific file or directory.
122
123 # Gets called for all changes to server.conf
124 $monitor->watch( 'server.conf', sub {
125 my ($file_name, $event, $change) = @_;
126 warn "Config file $file_name has changed\n";
127 } );
128
129 # Gets called if the owner of server.conf changes
130 $monitor->watch( {
131 name => 'server.conf',
132 callback => {
133 uid => sub {
134 my ($file_name, $event, $change) = @_;
135 warn "$file_name has changed owner\n";
136 }
137 }
138 } );
139
140 This last example shows the canonical way of specifying the arguments to
141 "watch" as a hash reference. See "watch" for more details.
142
143 Directories
144 When monitoring a directory you can choose to ignore its contents, scan
145 its contents one level deep or perform a recursive scan of all its
146 subdirectories.
147
148 See File::Monitor::Object for more information and caveats.
149
150INTERFACE
151 "new( %args )"
152 Create a new "File::Monitor" object. Any options should be passed as
153 a reference to a hash as follows:
154
155 my $monitor = File::Monitor->new( {
156 base => $some_dir,
157 callback => {
158 uid => sub {
159 my ($file_name, $event, $change) = @_;
160 warn "$file_name has changed owner\n";
161 },
162 size => sub {
163 my ($file_name, $event, $change) = @_;
164 warn "$file_name has changed size\n";
165 }
166 } );
167
168 Both options ("base" and "callback") are optional.
169
170 The "base" option specifies a base directory. When a base directory
171 has been specified all pathnames will internally be stored relative
172 to it. This doesn't affect the public interface which still uses
173 absolute paths but it does makes it possible to relocate a
174 File::Monitor if the directory it's watching is moved.
175
176 The "callback" option must be a reference to a hash that maps event
177 types to handler subroutines. See File::Monitor::Delta for a full
178 list of available event types.
179
180 "watch( $name, $callback | { args } )"
181 Create a new File::Monitor::Object and add it to this monitor.
182
183 The passed hash reference contains various options as follows:
184
185 $monitor->watch( {
186 name => $file_or_directory_name,
187 recurse => $should_recurse_directory,
188 files => $should_read_files_in_directory,
189 callback => {
190 $some_event => sub {
191 # Handler for $some_event
192 },
193 $other_event => sub {
194 # Handler for $other_event
195 }
196 }
197 } );
198
199 Here are those options in more detail:
200
201 "name"
202 The name of the file or directory to be monitored. Relative
203 paths will be made absolute relative to the current directory at
204 the time of the call. This option is mandatory; "new" will croak
205 if it is missing.
206
207 "recurse"
208 If this is a directory and "recurse" is true monitor the entire
209 directory tree below this directory.
210
211 "files"
212 If this is a directory and "files" is true monitor the files and
213 directories immediately below this directory but don't recurse
214 down the directory tree.
215
216 Note that if you specify "recurse" or "files" only the *names*
217 of contained files will be monitored. Changes to the contents of
218 contained files are not detected.
219
220 "callback"
221 Provides a reference to a hash of callback handlers the keys of
222 which are the names of events as described in
223 File::Monitor::Delta.
224
225 Callback subroutines are called with the following arguments:
226
227 $name
228 The name of the file or directory that has changed.
229
230 $event
231 The type of change. If the callback was registered for a
232 specific event it will be passed here. The actual event may be
233 one of the events below the specified event in the event
234 hierarchy. See File::Monitor::Delta for more details.
235
236 $delta
237 The File::Monitor::Delta object that describes this change.
238
239 As a convenience "watch" may be called with a simpler form of
240 arguments:
241
242 $monitor->watch( $name );
243
244 is equivalent to
245
246 $monitor->watch( {
247 name => $name
248 } );
249
250 And
251
252 $monitor->watch( $name, $callback );
253
254 is eqivalent to
255
256 $monitor->watch( {
257 name => $name
258 callback => {
259 change => $callback
260 }
261 } );
262
263 "unwatch( $name )"
264 Remove the watcher (if any) that corresponds with the specified file
265 or directory.
266
267 my $file = 'config.cfg';
268 $monitor->watch( $file ); # Now we're watching it
269
270 $monitor->unwatch( $file ); # Now we're not
271
272 "scan()"
273 Perform a scan of all monitored files and directories and return a
274 list of changes. Any callbacks that are registered will have been
275 triggered before "scan" returns.
276
277 When "scan" is first called the current state of the various
278 monitored files and directories will be captured but no changes will
279 be reported.
280
281 The return value is a list of File::Monitor::Delta objects, one for
282 each changed file or directory.
283
284 my @changes = $monitor->scan;
285
286 for my $change ( @changes ) {
287 warn $change->name, " changed\n";
288 }
289
290 "callback( [ $event, ] $coderef )"
291 Register a callback. If $event is omitted the callback will be
292 called for all changes. Specify $event to limit the callback to
293 certain event types. See File::Monitor::Delta for a full list of
294 events.
295
296 $monitor->callback( sub {
297 # called for all changes
298 } );
299
300 $monitor->callback( metadata => sub {
301 # called for changes to file/directory metatdata
302 } );
303
304 The callback subroutine will be called with the following arguments:
305
306 $name
307 The name of the file or directory that has changed.
308
309 $event
310 The type of change. If the callback was registered for a
311 specific event it will be passed here. The actual event may be
312 one of the events below the specified event in the event
313 hierarchy. See File::Monitor::Delta for more details.
314
315 $delta
316 The File::Monitor::Delta object that describes this change.
317
318 "base"
319 Get or set the base directory. This allows the entire monitor tree
320 to be relocated.
321
322 # Create a monitor and watch a couple of files
323 my $monitor = File::Monitor->new( { base => $some_dir } );
324 $monitor->watch( "$some_dir/source.c" );
325 $monitor->watch( "$some_dir/notes.text" );
326
327 # Now move the directory and patch up the monitor
328 rename( $some_dir, $other_dir );
329 $monitor->base( $other_dir );
330
331 # Still works
332 my @changes = $monitor->scan;
333
334 If you are going to specify a base directory you must do so before
335 any watches are added.
336
337 "has_monitors"
338 Returns true if this File::Monitor has any monitors attached to it.
339 Used internally to police the restriction that a base directory may
340 not be set when monitors have been added.
341
342DIAGNOSTICS
343 "A filename must be specified"
344 You must pass "unwatch" the name of a file or directory to stop
345 watching.
346
347CONFIGURATION AND ENVIRONMENT
348 File::Monitor requires no configuration files or environment variables.
349
350DEPENDENCIES
351 None.
352
353INCOMPATIBILITIES
354 None reported.
355
356BUGS AND LIMITATIONS
357 No bugs have been reported.
358
359 Please report any bugs or feature requests to
360 "bug-file-monitor@rt.cpan.org", or through the web interface at
361 <http://rt.cpan.org>.
362
363AUTHOR
364 Andy Armstrong "<andy@hexten.net>"
365
366 Faycal Chraibi originally registered the File::Monitor namespace and
367 then kindly handed it to me.
368
369LICENCE AND COPYRIGHT
370 Copyright (c) 2007, Andy Armstrong "<andy@hexten.net>". All rights
371 reserved.
372
373 This module is free software; you can redistribute it and/or modify it
374 under the same terms as Perl itself. See perlartistic.
375
376DISCLAIMER OF WARRANTY
377 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
378 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
379 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
380 PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
381 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
382 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
383 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
384 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
385 NECESSARY SERVICING, REPAIR, OR CORRECTION.
386
387 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
388 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
389 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
390 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
391 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
392 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
393 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
394 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
395 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
396 DAMAGES.
397
398