NAME

VERSION

SYNOPSIS

    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";
        }
    }

DESCRIPTION

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").

Unless you are writing a subclass of "File::Monitor::Object" it isn't normally necessary to instantiate "File::Monitor::Delta" objects directly.

    change
        created
        deleted
        metadata
            time
                mtime
                ctime
            perms
                uid
                gid
                mode
            size
        directory
            files_created
            files_deleted

    $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

    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

    my $mode_was = $delta->old_mode;

    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;

    created deleted mtime ctime uid gid mode size

    my $grown_by = $delta->size;

    my $grown_by = $delta->new_size - $delta->old_size;

    # Get the difference between the old and new UID. Unlikely to be
    # interesting.
    my $delta_uid = $delta->uid;

    my $bits_changed = $delta->mode;

    if ( $delta->created ) {
        print "Yippee! We exist\n";
    }

    if ( $delta->deleted ) {
        print "Boo! We got deleted\n";
    }

    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";
    }

INTERFACE

"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:

"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

    change created deleted metadata time mtime ctime perms uid gid
    mode size directory files_created files_deleted
    

As an alternative interface you may call "is_"eventname directly. For example

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

"name"

The name of the file for which the change is being reported. Read only.

"object"

The File::Monitor::Object for which this change is being reported.

    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

DIAGNOSTICS

"%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.

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

Please report any bugs or feature requests to "bug-file-monitor@rt.cpan.org", or through the web interface at <http://rt.cpan.org>.

AUTHOR

Faycal Chraibi originally registered the File::Monitor namespace and then kindly handed it to me.

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

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.