File::...:Delta(3pm)

📦
version 1.00 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay so bestie, welcome to the manual page for File::Monitor::Delta — that's the perl user-contributed docs section, 3pm, if you were wondering where you wandered into 🌸. It does exactly one (1) iconique job: it encapsulates a change to a file or directory. that's it. that's the whole vibe. periodt.

✨ VERSION ✨

This document describes File::Monitor::Delta version 1.00 🎀

🦋 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 💅

so when File::Monitor or File::Monitor::Object catches a change to a file or directory, it wraps up all the deets about that change in a File::Monitor::Delta object. it's like a little gift box of "here's what happened" 🎁

you've got methods to figure out what kind of change it was (is_event and friends), methods to pull the attributes of the file or directory from before and after (old_mtime, old_mode, new_mtime, new_mode, etc.), methods that hand you the whole story in a convenient form (files_created, files_deleted), and a method to get at the actual File::Monitor::Object the change was spotted on (object).

lowkey though? unless you're out here writing a subclass of File::Monitor::Object you don't normally need to make File::Monitor::Delta objects yourself. the machinery does it for you. let it cook 👑

🌈 Changes Classified 🌈

there are various types of change, and they get sorted into this whole hierarchy, and honestly the structure ate:

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 — are the actual change events. the non-terminal nodes are just broader categories of events. so for example, if a file's mtime changes, the resulting File::Monitor::Delta object will return true for each of:

$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 whole classification system exists so you can aim your callbacks at super specific events or at whole categories of events. see File::Monitor and File::Monitor::Object if you want the callback tea 🍓

🧚 Accessors 🧚

a whole bunch of accessors let you query the state of the object before and after the change, plus the details of the change itself. very "tell me everything" of them ✨

these accessors give you the state of the file or directory before the change was detected:

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

like, for example:

my $mode_was = $delta->old_mode;

these accessors give you the state after the change was detected:

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

for example:

my $new_size = $delta->new_size;

and these accessors give you 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. and ngl, that's only actually useful in the case of size:

my $grown_by = $delta->size;

which is equivalent to

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

for the other values the subtraction is performed merely to make sure those values are non-zero. that's the whole reason. iconic behaviour honestly.

# 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. so the old mode is XORed with the new mode, which means

my $bits_changed = $delta->mode;

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

and for a directory that's being monitored with the recurse or files options (peep File::Monitor::Object for the details, bestie), 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.

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 get created as necessary by File::Monitor::Object, so like, chill.

the single argument is a reference to a hash that must contain these keys:

  • object — the File::Monitor::Object for which this change is being reported.
  • old_info — a hash describing the state of the file or directory before the change.
  • new_info — 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. so like, if a file's size changes, all of these 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 the cleaner, less error prone interface. it just is 💜

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. so if you got one? something changed. slay.

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.

🌸 Other methods 🌸

as mentioned above, a large number of other accessors are provided to get the state of the object before and after the change and to query the 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 👆

💀 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. it's set in its ways and it's thriving ✨
  • "You must supply a value for %s" — the three options that new takes (old_info, new_info and object) are all mandatory. no skipping. no "I'll do it later". supply them.

🌈 CONFIGURATION AND ENVIRONMENT 🌈

File::Monitor::Delta requires no configuration files or environment variables. zero setup, zero drama, we love that for us 💖

🎀 DEPENDENCIES 🎀

None. not a single one. self-sufficient queen 👑

🙈 INCOMPATIBILITIES 🙈

None reported. no beef with anybody.

😭 BUGS AND LIMITATIONS 😭

No bugs have been reported. (iconic, no notes 🫶)

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 ⭐

Andy Armstrong <andy@hexten.net>

Faycal Chraibi originally registered the File::Monitor namespace and then kindly handed it to me. shoutout Faycal, that was so sweet of them fr fr 🥹

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.

💅 DISCLAIMER OF WARRANTY 💅

okay bestie, this next bit is the legal bit and it is giving SERIOUS all-caps energy. reading it in full, no skimming, because it genuinely matters:

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.

so like… no warranty, that's the whole point, but you already knew that 💀

and that's a wrap bestie!! this page was brought to you by perl v5.36.0 and dated 2022-10-21 🎀 ty for reading, go check your file sizes, ily, bye 💖✨

📦 where this page comes from