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

FreeBSD Manual Pages

  
 
  

home | help
File::Modified(3)     User Contributed Perl Documentation    File::Modified(3)

NAME
       File::Modified -	checks intelligently if	files have changed

SYNOPSIS
	 use strict;
	 use File::Modified;

	 my $d = File::Modified->new(files=>['Import.cfg','Export.cfg']);

	 while (1) {
	   my (@changes) = $d->changed;

	   if (@changes) {
	     print "$_ was changed\n" for @changes;
	     $d->update();
	   };
	   sleep 60;
	 };

       Second example -	a script that knows when any of	its modules have
       changed :

	 use File::Modified;
	 my $files = File::Modified->new(files=>[values	%INC, $0]);

	 # We want to restart when any module was changed
	 exec $0, @ARGV	if $files->changed();

DESCRIPTION
       This module provides a simple mechanism for identifying when the
       contents	of one or more files have changed.  It was initially intended
       for programs to detect when their configuration files (or the module
       they rely on) have changed.

       There are currently two methods of change detection implemented,
       "mtime" and "MD5".  The "MD5" method will fall back to use timestamps
       if the "Digest::MD5" module cannot be loaded.

       There are a number of other modules on CPAN that	provide	similar
       functionality; they are listed in "SEE ALSO" below.

       new %ARGS
	   Creates a new instance. The %ARGS hash has two possible keys,
	   "Method", which denotes the method used for checking	as default,
	   and "Files",	which takes an array reference to the filenames	to
	   watch.

       add filename, method
	   Adds	a new file to watch. "method" is the method (or	rather,	the
	   subclass of "File::Modified::Signature") to use to determine
	   whether a file has changed or not. The result is either the
	   "File::Modified::Signature" subclass	or undef if an error occurred.

       addfile LIST
	   Adds	a list of files	to watch. The method used for watching is the
	   default method as set in the	constructor. The result	is a list of
	   "File::Modified::Signature" subclasses.

       update
	   Updates all signatures to the current state.	All pending changes
	   are discarded.

       changed
	   Returns a list of the filenames whose files did change since	the
	   construction	or the last call to "update" (whichever	last
	   occurred).

   Signatures
       The module also creates a new namespace "File::Signature", which
       sometime	will evolve into its own module	in its own file. A file
       signature is most likely	of little interest to you; the only time you
       might want to access the	signature directly is to store the signature
       in a file for persistence and easy comparision whether an index
       database	is current with	the actual data.

       The interface is	settled, there are two methods,	"as_scalar" and
       "from_scalar", that you use to freeze and thaw the signatures. The
       implementation of these methods is very frugal, there are no provisions
       made against filenames that contain weird characters like "\n" or "|"
       (the pipe bar), both will be likely to mess up your one-line-per-file
       database. An interesting	method could be	to URL-encode all filenames,
       but I will visit	this topic in the next release.	Also, complex (that
       is, non-scalar) signatures are handled rather ungraceful	at the moment.

       Currently, I'm planning to use Text::Quote as a quoting mechanism to
       protect against multiline filenames.

   Adding new methods for signatures
       Adding a	new signature method is	as simple as creating a	new subclass
       of "File::Signature". See "File::Signature::Checksum" for a simple
       example.	There is one point of laziness in the implementation of
       "File::Signature", the "check" method can only compare strings instead
       of arbitrary structures (yes, there ARE things that are easier in
       Python than in Perl). "File::Signature::Digest" is a wrapper for	Gisle
       Aas' Digest module and allows you to use	any module below the "Digest"
       namespace as a signature, for example "File::Signature::MD5" and
       "File::Signature::SHA1".

   TODO
       * Make the simple persistence solution for the signatures better	using
       Text::Quote.

       * Allow complex structures for the signatures.

       * Document "File::Modified::Signature" or put it	down into another
       namespace.

       * Extract the "File::Modified::Signature" subclasses out	into their own
       file.

       * Create	an easy	option to watch	a whole	directory tree.

   EXPORT
       None by default.

SEE ALSO
       File::Monitor will watch	a file or directory, invoking a	callback when
       it changes.

       File::Monitor::Lite is similar to File::Monitor,	but can	also let you
       know about new files being created.

       File::Monitor::Simple watches a directory for changes to	any files
       whose name matches a regular expression.

       File::IfModified	provides a function that can be	used to	check whether
       a file has been modified	since the last time you	checked.

       File::ChangeNotify provides an API for watching all files in a given
       directory. It provides several mechanisms for doing this, and a base-
       class that you can subclass to write your own watcher.

       File::Signature provides	some lower-level functions than
       File::Modified, which are used to identify whether a file has changed
       by comparing its	MD5 digest with	an earlier snapshot.

       File::Stat::Trigger will	invoke one of your callbacks if	the "stat()"
       details of a file change.

       Win32::FileSystem::Watcher provides a Windows-specific solution for
       watching	for changes to a filesystem.  The documentation	is extremely
       limited,	so I can't tell	if you can limit it a specific directory.

       App::watcher comes with a script	that will run a	command	if any of the
       files in	a directory are	changed.

       IO::Async::File watches an open filehandle or 'named filesystem entity'
       for changes in its "stat()" fields.

       POE::Component::DirWatch	watches	a directory for	new files or
       directories, invoking a user-supplied callback function when one	is
       seen.

       WWW::Monitor is similar to File::Monitor, but checks URLs rather	than
       files.

REPOSITORY
       <https://github.com/neilb/File-Modified>

COPYRIGHT AND LICENSE
       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

       Copyright (C) 2002 Max Maischein

AUTHOR
       Max Maischein, <corion@cpan.org>

       Please contact me if you	find bugs or otherwise improve the module.
       More tests are also very	welcome	!

perl v5.32.1			  2015-10-26		     File::Modified(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | REPOSITORY | COPYRIGHT AND LICENSE | AUTHOR

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

home | help