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.
Addingnewmethodsforsignatures
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.
Install Now
