1File::Modified(3) User Contributed Perl Documentation File::Modified(3)
2
6 File::Modified - checks intelligently if files have changed
7
9 use strict;
10 use File::Modified;
11 my $d = File::Modified->new(files=>['Import.cfg','Export.cfg']);
13 while (1) {
15 my (@changes) = $d->changed;
16 if (@changes) {
18 print "$_ was changed\n" for @changes;
19 $d->update();
20 };
21 sleep 60;
22 };
23 Second example - a script that knows when any of its modules have
25 changed :
26 use File::Modified;
28 my $files = File::Modified->new(files=>[values %INC, $0]);
29 # We want to restart when any module was changed
31 exec $0, @ARGV if $files->changed();
32
34 This module provides a simple mechanism for identifying when the
35 contents of one or more files have changed. It was initially intended
36 for programs to detect when their configuration files (or the module
37 they rely on) have changed.
38 There are currently two methods of change detection implemented,
40 "mtime" and "MD5". The "MD5" method will fall back to use timestamps
41 if the "Digest::MD5" module cannot be loaded.
42 There are a number of other modules on CPAN that provide similar
44 functionality; they are listed in "SEE ALSO" below.
45 new %ARGS
47 Creates a new instance. The %ARGS hash has two possible keys,
48 "Method", which denotes the method used for checking as default,
49 and "Files", which takes an array reference to the filenames to
50 watch.
51 add filename, method
53 Adds a new file to watch. "method" is the method (or rather, the
54 subclass of "File::Modified::Signature") to use to determine
55 whether a file has changed or not. The result is either the
56 "File::Modified::Signature" subclass or undef if an error occurred.
57 addfile LIST
59 Adds a list of files to watch. The method used for watching is the
60 default method as set in the constructor. The result is a list of
61 "File::Modified::Signature" subclasses.
62 update
64 Updates all signatures to the current state. All pending changes
65 are discarded.
66 changed
68 Returns a list of the filenames whose files did change since the
69 construction or the last call to "update" (whichever last
70 occurred).
71 Signatures
73 The module also creates a new namespace "File::Signature", which
74 sometime will evolve into its own module in its own file. A file
75 signature is most likely of little interest to you; the only time you
76 might want to access the signature directly is to store the signature
77 in a file for persistence and easy comparision whether an index
78 database is current with the actual data.
79 The interface is settled, there are two methods, "as_scalar" and
81 "from_scalar", that you use to freeze and thaw the signatures. The
82 implementation of these methods is very frugal, there are no provisions
83 made against filenames that contain weird characters like "\n" or "|"
84 (the pipe bar), both will be likely to mess up your one-line-per-file
85 database. An interesting method could be to URL-encode all filenames,
86 but I will visit this topic in the next release. Also, complex (that
87 is, non-scalar) signatures are handled rather ungraceful at the moment.
88 Currently, I'm planning to use Text::Quote as a quoting mechanism to
90 protect against multiline filenames.
91 Adding new methods for signatures
93 Adding a new signature method is as simple as creating a new subclass
94 of "File::Signature". See "File::Signature::Checksum" for a simple
95 example. There is one point of laziness in the implementation of
96 "File::Signature", the "check" method can only compare strings instead
97 of arbitrary structures (yes, there ARE things that are easier in
98 Python than in Perl). "File::Signature::Digest" is a wrapper for Gisle
99 Aas' Digest module and allows you to use any module below the "Digest"
100 namespace as a signature, for example "File::Signature::MD5" and
101 "File::Signature::SHA1".
102 TODO
104 * Make the simple persistence solution for the signatures better using
105 Text::Quote.
106 * Allow complex structures for the signatures.
108 * Document "File::Modified::Signature" or put it down into another
110 namespace.
111 * Extract the "File::Modified::Signature" subclasses out into their own
113 file.
114 * Create an easy option to watch a whole directory tree.
116 EXPORT
118 None by default.
119
121 File::Monitor will watch a file or directory, invoking a callback when
122 it changes.
123 File::Monitor::Lite is similar to File::Monitor, but can also let you
125 know about new files being created.
126 File::Monitor::Simple watches a directory for changes to any files
128 whose name matches a regular expression.
129 File::IfModified provides a function that can be used to check whether
131 a file has been modified since the last time you checked.
132 File::ChangeNotify provides an API for watching all files in a given
134 directory. It provides several mechanisms for doing this, and a base-
135 class that you can subclass to write your own watcher.
136 File::Signature provides some lower-level functions than
138 File::Modified, which are used to identify whether a file has changed
139 by comparing its MD5 digest with an earlier snapshot.
140 File::Stat::Trigger will invoke one of your callbacks if the "stat()"
142 details of a file change.
143 Win32::FileSystem::Watcher provides a Windows-specific solution for
145 watching for changes to a filesystem. The documentation is extremely
146 limited, so I can't tell if you can limit it a specific directory.
147 App::watcher comes with a script that will run a command if any of the
149 files in a directory are changed.
150 IO::Async::File watches an open filehandle or 'named filesystem entity'
152 for changes in its "stat()" fields.
153 POE::Component::DirWatch watches a directory for new files or
155 directories, invoking a user-supplied callback function when one is
156 seen.
157 WWW::Monitor is similar to File::Monitor, but checks URLs rather than
159 files.
160
162 <https://github.com/neilb/File-Modified>
163
165 This library is free software; you can redistribute it and/or modify it
166 under the same terms as Perl itself.
167 Copyright (C) 2002 Max Maischein
169
171 Max Maischein, <corion@cpan.org>
172 Please contact me if you find bugs or otherwise improve the module.
174 More tests are also very welcome !
175perl v5.28.0 2015-10-26 File::Modified(3)