File::Monitor::Delta - Encapsulate a change to a file or directory
This document describes File::Monitor::Delta version 1.00
use File::Monitor; my $monitor = File::Monitor->new(); # Watch some files for my $file (qw( myfile.txt yourfile.txt otherfile.txt some_directory )) { $monitor->watch( $file ); } # First scan just finds out about the monitored files. No changes # will be reported. $object->scan; # After the first scan we get a list of File::Monitor::Delta objects # that describe any changes my @changes = $object->scan; for my $change (@changes) { # Call methods on File::Monitor::Delta to discover what changed if ($change->is_size) { my $name = $change->name; my $old_size = $change->old_size; my $new_size = $change->new_size; print "$name has changed size from $old_size to $new_size\n"; } }
When File::Monitor or File::Monitor::Object detects a change to a file or directory it packages the details of the change in a File::Monitor::Delta object.
File::Monitor::Delta
Methods exist to discover the nature of the change (is_event et al.), retrieve the attributes of the file or directory before and after the change (old_mtime, old_mode, new_mtime, new_mode etc), retrieve details of the change in a convenient form (files_created, files_deleted) and gain access to the File::Monitor::Object for which the change was observed (object).
is_event
old_mtime
old_mode
new_mtime
new_mode
files_created
files_deleted
object
Unless you are writing a subclass of File::Monitor::Object it isn't normally necessary to instantiate File::Monitor::Delta objects directly.
File::Monitor::Object
Various types of change are identified and classified into the following hierarchy:
change created deleted metadata time mtime ctime perms uid gid mode size directory files_created files_deleted
The terminal nodes of that tree (created, deleted, mtime, ctime, uid, gid, mode, size, files_created and files_deleted) represent actual change events. Non terminal nodes represent broader classifications of events. For example if a file's mtime changes the resulting File::Monitor::Delta object will return true for each of
created
deleted
mtime
ctime
uid
gid
mode
size
$delta->is_mtime; # The actual change $delta->is_time; # One of the file times changed $delta->is_metadata; # The file's metadata changed $delta->is_change; # This is true for any change
This event classification is used to target callbacks at specific events or categories of events. See File::Monitor and File::Monitor::Object for more information about callbacks.
Various accessors allow the state of the object before and after the change and the details of the change to be queried.
These accessors return information about the state of the file or directory before the detected change:
old_dev old_inode old_mode old_num_links old_uid old_gid old_rdev old_size old_mtime old_ctime old_blk_size old_blocks old_error old_files
For example:
my $mode_was = $delta->old_mode;
These accessors return information about the state of the file or directory after the detected change:
new_dev new_inode new_mode new_num_links new_uid new_gid new_rdev new_size new_mtime new_ctime new_blk_size new_blocks new_error new_files
my $new_size = $delta->new_size;
These accessors return a value that reflects the change in the corresponding attribute:
created deleted mtime ctime uid gid mode size
With the exception of mode, created and deleted they return the difference between the old value and the new value. This is only really useful in the case of size:
my $grown_by = $delta->size;
Is equivalent to
my $grown_by = $delta->new_size - $delta->old_size;
For the other values the subtraction is performed merely to ensure that these values are non-zero.
# Get the difference between the old and new UID. Unlikely to be # interesting. my $delta_uid = $delta->uid;
As a special case the delta value for mode is computed as old_mode ^ new_mode. The old mode is XORed with the new mode so that
my $bits_changed = $delta->mode;
gets a bitmask of the mode bits that have changed.
If the detected change was the creation or deletion of a file created or deleted respectively will be true.
if ( $delta->created ) { print "Yippee! We exist\n"; } if ( $delta->deleted ) { print "Boo! We got deleted\n"; }
For a directory which is being monitored with the recurse or files options (see File::Monitor::Object for details) files_created and files_deleted will contain respectively the list of new files below this directory and the list of files that have been deleted.
recurse
files
my @new_files = $delta->files_created; for my $file ( @new_files ) { print "$file created\n"; } my @gone_away = $delta->files_deletedl for my $file ( @gone_away ) { print "$file deleted\n"; }
new( $args )
Create a new File::Monitor::Delta object. You don't normally need to do this; deltas are created as necessary by File::Monitor::Object.
The single argument is a reference to a hash that must contain the following keys:
The File::Monitor::Object for which this change is being reported.
A hash describing the state of the file or directory before the change.
A hash describing the state of the file or directory after the change.
is_event( $event )
Returns true if this delta represents the specified event. For example, if a file's size changes the following will all return true:
$delta->is_event('size'); # The actual change $delta->is_event('metadata'); # The file's metadata changed $delta->is_event('change'); # This is true for any change
Valid eventnames are
As an alternative interface you may call is_eventname directly. For example
is_
$delta->is_size; $delta->is_metadata; $delta->is_change;
Unless the event you wish to test for is variable this is a cleaner, less error prone interface.
Normally your code won't see a File::Monitor::Delta for which is_change returns false. Any change causes is_change to be true and the scan methods of File::Monitor and File::Monitor::Object don't return deltas for unchanged files.
is_change
scan
File::Monitor
name
The name of the file for which the change is being reported. Read only.
As mentioned above a large number of other accessors are provided to get the state of the object before and after the change and query details of the change:
old_dev old_inode old_mode old_num_links old_uid old_gid old_rdev old_size old_mtime old_ctime old_blk_size old_blocks old_error old_files new_dev new_inode new_mode new_num_links new_uid new_gid new_rdev new_size new_mtime new_ctime new_blk_size new_blocks new_error new_files created deleted mtime ctime uid gid mode size files_created files_deleted name
See "Accessors" for details of these.
%s is read-only
File::Monitor::Delta is an immutable description of a change in a file's state. None of its accessors allow values to be changed.
You must supply a value for %s
The three options that new (old_info, new_info and object) are all mandatory.
new
old_info
new_info
File::Monitor::Delta requires no configuration files or environment variables.
None.
None reported.
No bugs have been reported.
Please report any bugs or feature requests to bug-file-monitor@rt.cpan.org, or through the web interface at http://rt.cpan.org.
bug-file-monitor@rt.cpan.org
Andy Armstrong <andy@hexten.net>
<andy@hexten.net>
Faycal Chraibi originally registered the File::Monitor namespace and then kindly handed it to me.
Copyright (c) 2007, Andy Armstrong <andy@hexten.net>. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
To install File::Monitor, copy and paste the appropriate command in to your terminal.
cpanm
cpanm File::Monitor
CPAN shell
perl -MCPAN -e shell install File::Monitor
For more information on module installation, please visit the detailed CPAN module installation guide.