.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "File::Monitor::Delta 3pm"
.TH File::Monitor::Delta 3pm "2022-10-21" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::Monitor::Delta \- Encapsulate a change to a file or directory
.SH "VERSION"
.IX Header "VERSION"
This document describes File::Monitor::Delta version 1.00
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    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\en";
\&        }
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
When File::Monitor or File::Monitor::Object detects a change to a
file or directory it packages the details of the change in a
\&\f(CW\*(C`File::Monitor::Delta\*(C'\fR object.
.PP
Methods exist to discover the nature of the change (\f(CW\*(C`is_event\*(C'\fR et al.),
retrieve the attributes of the file or directory before and after the
change (\f(CW\*(C`old_mtime\*(C'\fR, \f(CW\*(C`old_mode\*(C'\fR, \f(CW\*(C`new_mtime\*(C'\fR, \f(CW\*(C`new_mode\*(C'\fR etc),
retrieve details of the change in a convenient form (\f(CW\*(C`files_created\*(C'\fR,
\&\f(CW\*(C`files_deleted\*(C'\fR) and gain access to the File::Monitor::Object for
which the change was observed (\f(CW\*(C`object\*(C'\fR).
.PP
Unless you are writing a subclass of \f(CW\*(C`File::Monitor::Object\*(C'\fR it
isn't normally necessary to instantiate \f(CW\*(C`File::Monitor::Delta\*(C'\fR
objects directly.
.SS "Changes Classified"
.IX Subsection "Changes Classified"
Various types of change are identified and classified into the following
hierarchy:
.PP
.Vb 10
\&    change
\&        created
\&        deleted
\&        metadata
\&            time
\&                mtime
\&                ctime
\&            perms
\&                uid
\&                gid
\&                mode
\&            size
\&        directory
\&            files_created
\&            files_deleted
.Ve
.PP
The terminal nodes of that tree (\f(CW\*(C`created\*(C'\fR, \f(CW\*(C`deleted\*(C'\fR, \f(CW\*(C`mtime\*(C'\fR,
\&\f(CW\*(C`ctime\*(C'\fR, \f(CW\*(C`uid\*(C'\fR, \f(CW\*(C`gid\*(C'\fR, \f(CW\*(C`mode\*(C'\fR, \f(CW\*(C`size\*(C'\fR, \f(CW\*(C`files_created\*(C'\fR and
\&\f(CW\*(C`files_deleted\*(C'\fR) represent actual change events. Non terminal nodes
represent broader classifications of events. For example if a file's
mtime changes the resulting \f(CW\*(C`File::Monitor::Delta\*(C'\fR object will return
true for each of
.PP
.Vb 4
\&    $delta\->is_mtime;       # The actual change
\&    $delta\->is_time;        # One of the file times changed
\&    $delta\->is_metadata;    # The file\*(Aqs metadata changed
\&    $delta\->is_change;      # This is true for any change
.Ve
.PP
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.
.SS "Accessors"
.IX Subsection "Accessors"
Various accessors allow the state of the object before and after the
change and the details of the change to be queried.
.PP
These accessors return information about the state of the file or
directory before the detected change:
.PP
.Vb 3
\&    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
.Ve
.PP
For example:
.PP
.Vb 1
\&    my $mode_was = $delta\->old_mode;
.Ve
.PP
These accessors return information about the state of the file or
directory after the detected change:
.PP
.Vb 3
\&    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
.Ve
.PP
For example:
.PP
.Vb 1
\&    my $new_size = $delta\->new_size;
.Ve
.PP
These accessors return a value that reflects the change in the
corresponding attribute:
.PP
.Vb 1
\&    created deleted mtime ctime uid gid mode size
.Ve
.PP
With the exception of \f(CW\*(C`mode\*(C'\fR, \f(CW\*(C`created\*(C'\fR and \f(CW\*(C`deleted\*(C'\fR they return
the difference between the old value and the new value. This is only
really useful in the case of \f(CW\*(C`size\*(C'\fR:
.PP
.Vb 1
\&    my $grown_by = $delta\->size;
.Ve
.PP
Is equivalent to
.PP
.Vb 1
\&    my $grown_by = $delta\->new_size \- $delta\->old_size;
.Ve
.PP
For the other values the subtraction is performed merely to ensure that
these values are non-zero.
.PP
.Vb 3
\&    # Get the difference between the old and new UID. Unlikely to be
\&    # interesting.
\&    my $delta_uid = $delta\->uid;
.Ve
.PP
As a special case the delta value for \f(CW\*(C`mode\*(C'\fR is computed as old_mode ^
new_mode. The old mode is XORed with the new mode so that
.PP
.Vb 1
\&    my $bits_changed = $delta\->mode;
.Ve
.PP
gets a bitmask of the mode bits that have changed.
.PP
If the detected change was the creation or deletion of a file \f(CW\*(C`created\*(C'\fR
or \f(CW\*(C`deleted\*(C'\fR respectively will be true.
.PP
.Vb 3
\&    if ( $delta\->created ) {
\&        print "Yippee! We exist\en";
\&    }
\&
\&    if ( $delta\->deleted ) {
\&        print "Boo! We got deleted\en";
\&    }
.Ve
.PP
For a directory which is being monitored with the \f(CW\*(C`recurse\*(C'\fR or \f(CW\*(C`files\*(C'\fR
options (see File::Monitor::Object for details) \f(CW\*(C`files_created\*(C'\fR and
\&\f(CW\*(C`files_deleted\*(C'\fR will contain respectively the list of new files below
this directory and the list of files that have been deleted.
.PP
.Vb 1
\&    my @new_files = $delta\->files_created;
\&
\&    for my $file ( @new_files ) {
\&        print "$file created\en";
\&    }
\&
\&    my @gone_away = $delta\->files_deletedl
\&
\&    for my $file ( @gone_away ) {
\&        print "$file deleted\en";
\&    }
.Ve
.SH "INTERFACE"
.IX Header "INTERFACE"
.ie n .IP """new( $args )""" 4
.el .IP "\f(CWnew( $args )\fR" 4
.IX Item "new( $args )"
Create a new \f(CW\*(C`File::Monitor::Delta\*(C'\fR object. You don't normally need to
do this; deltas are created as necessary by File::Monitor::Object.
.Sp
The single argument is a reference to a hash that must contain the
following keys:
.RS 4
.IP "object" 4
.IX Item "object"
The File::Monitor::Object for which this change is being reported.
.IP "old_info" 4
.IX Item "old_info"
A hash describing the state of the file or directory before the change.
.IP "new_info" 4
.IX Item "new_info"
A hash describing the state of the file or directory after the change.
.RE
.RS 4
.RE
.ie n .IP """is_event( $event )""" 4
.el .IP "\f(CWis_event( $event )\fR" 4
.IX Item "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:
.Sp
.Vb 3
\&    $delta\->is_event(\*(Aqsize\*(Aq);        # The actual change
\&    $delta\->is_event(\*(Aqmetadata\*(Aq);    # The file\*(Aqs metadata changed
\&    $delta\->is_event(\*(Aqchange\*(Aq);      # This is true for any change
.Ve
.Sp
Valid eventnames are
.Sp
.Vb 2
\&    change created deleted metadata time mtime ctime perms uid gid
\&    mode size directory files_created files_deleted
.Ve
.Sp
As an alternative interface you may call \f(CW\*(C`is_\*(C'\fR\fIeventname\fR directly.
For example
.Sp
.Vb 3
\&    $delta\->is_size;
\&    $delta\->is_metadata;
\&    $delta\->is_change;
.Ve
.Sp
Unless the event you wish to test for is variable this is a cleaner,
less error prone interface.
.Sp
Normally your code won't see a \f(CW\*(C`File::Monitor::Delta\*(C'\fR for which
\&\f(CW\*(C`is_change\*(C'\fR returns false. Any change causes \f(CW\*(C`is_change\*(C'\fR to be true
and the \f(CW\*(C`scan\*(C'\fR methods of \f(CW\*(C`File::Monitor\*(C'\fR and \f(CW\*(C`File::Monitor::Object\*(C'\fR
don't return deltas for unchanged files.
.ie n .IP """name""" 4
.el .IP "\f(CWname\fR" 4
.IX Item "name"
The name of the file for which the change is being reported. Read only.
.ie n .IP """object""" 4
.el .IP "\f(CWobject\fR" 4
.IX Item "object"
The File::Monitor::Object for which this change is being reported.
.SS "Other methods"
.IX Subsection "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 query details of
the change:
.PP
.Vb 6
\&    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
.Ve
.PP
See \*(L"Accessors\*(R" for details of these.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP """%s is read\-only""" 4
.el .IP "\f(CW%s is read\-only\fR" 4
.IX Item "%s is read-only"
\&\f(CW\*(C`File::Monitor::Delta\*(C'\fR is an immutable description of a change in a
file's state. None of its accessors allow values to be changed.
.ie n .IP """You must supply a value for %s""" 4
.el .IP "\f(CWYou must supply a value for %s\fR" 4
.IX Item "You must supply a value for %s"
The three options that \f(CW\*(C`new\*(C'\fR (\f(CW\*(C`old_info\*(C'\fR, \f(CW\*(C`new_info\*(C'\fR and \f(CW\*(C`object\*(C'\fR)
are all mandatory.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
File::Monitor::Delta requires no configuration files or environment variables.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
None.
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.PP
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-file\-monitor@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Armstrong  \f(CW\*(C`<andy@hexten.net>\*(C'\fR
.PP
Faycal Chraibi originally registered the File::Monitor namespace and
then kindly handed it to me.
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2007, Andy Armstrong \f(CW\*(C`<andy@hexten.net>\*(C'\fR. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE 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 \*(L"AS IS\*(R" 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.\s0
.PP
\&\s-1IN 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\s0 (\s-1INCLUDING 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\s0), \s-1EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.\s0