Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
File::Monitor::Delta(3User Contributed Perl DocumentatiFile::Monitor::Delta(3)

NAME
       File::Monitor::Delta - Encapsulate a change to a	file or	directory

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

       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.

   Changes Classified
       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

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

   Accessors
       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

       For example:

	   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.

	   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:

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

   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:

	   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.

       "You must supply	a value	for %s"
	   The three options that "new"	("old_info", "new_info"	and "object")
	   are all mandatory.

CONFIGURATION AND ENVIRONMENT
       File::Monitor::Delta requires no	configuration files or environment
       variables.

DEPENDENCIES
       None.

INCOMPATIBILITIES
       None reported.

BUGS AND LIMITATIONS
       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>.

AUTHOR
       Andy Armstrong  "<andy@hexten.net>"

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

LICENCE	AND COPYRIGHT
       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
       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.

perl v5.32.1			  2010-10-27	       File::Monitor::Delta(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | INTERFACE | DIAGNOSTICS | CONFIGURATION AND ENVIRONMENT | DEPENDENCIES | INCOMPATIBILITIES | BUGS AND LIMITATIONS | AUTHOR | LICENCE AND COPYRIGHT | DISCLAIMER OF WARRANTY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=File::Monitor::Delta&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help