File::Modified(3) User Contributed Perl Documentation File::Modified(3)NAMEFile::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
The Modified module is intended as a simple method for programs to
detect whether configuration files (or modules 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 is another module, File::Signature, which has many similar
features, so if this module doesn't do what you need, maybe
File::Signature does. There also is quite some overlap between the two
modules, code wise.
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.
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 !
SEE ALSO
perl,Digest::MD5,Digest, File::Signature.
perl v5.14.1 2004-12-05 File::Modified(3)
