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

       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.