1File::Modified(3)     User Contributed Perl Documentation    File::Modified(3)
2
3
4

NAME

6       File::Modified - checks intelligently if files have changed
7

SYNOPSIS

9         use strict;
10         use File::Modified;
11
12         my $d = File::Modified->new(files=>['Import.cfg','Export.cfg']);
13
14         while (1) {
15           my (@changes) = $d->changed;
16
17           if (@changes) {
18             print "$_ was changed\n" for @changes;
19             $d->update();
20           };
21           sleep 60;
22         };
23
24       Second example - a script that knows when any of its modules have
25       changed :
26
27         use File::Modified;
28         my $files = File::Modified->new(files=>[values %INC, $0]);
29
30         # We want to restart when any module was changed
31         exec $0, @ARGV if $files->changed();
32

DESCRIPTION

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
39       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
43       There are a number of other modules on CPAN that provide similar
44       functionality; they are listed in "SEE ALSO" below.
45
46       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
52       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
58       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
63       update
64           Updates all signatures to the current state. All pending changes
65           are discarded.
66
67       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
72   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
80       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
89       Currently, I'm planning to use Text::Quote as a quoting mechanism to
90       protect against multiline filenames.
91
92   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
103   TODO
104       * Make the simple persistence solution for the signatures better using
105       Text::Quote.
106
107       * Allow complex structures for the signatures.
108
109       * Document "File::Modified::Signature" or put it down into another
110       namespace.
111
112       * Extract the "File::Modified::Signature" subclasses out into their own
113       file.
114
115       * Create an easy option to watch a whole directory tree.
116
117   EXPORT
118       None by default.
119

SEE ALSO

121       File::Monitor will watch a file or directory, invoking a callback when
122       it changes.
123
124       File::Monitor::Lite is similar to File::Monitor, but can also let you
125       know about new files being created.
126
127       File::Monitor::Simple watches a directory for changes to any files
128       whose name matches a regular expression.
129
130       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
133       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
137       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
141       File::Stat::Trigger will invoke one of your callbacks if the "stat()"
142       details of a file change.
143
144       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
148       App::watcher comes with a script that will run a command if any of the
149       files in a directory are changed.
150
151       IO::Async::File watches an open filehandle or 'named filesystem entity'
152       for changes in its "stat()" fields.
153
154       POE::Component::DirWatch watches a directory for new files or
155       directories, invoking a user-supplied callback function when one is
156       seen.
157
158       WWW::Monitor is similar to File::Monitor, but checks URLs rather than
159       files.
160

REPOSITORY

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
168       Copyright (C) 2002 Max Maischein
169

AUTHOR

171       Max Maischein, <corion@cpan.org>
172
173       Please contact me if you find bugs or otherwise improve the module.
174       More tests are also very welcome !
175
176
177
178perl v5.28.0                      2015-10-26                 File::Modified(3)
Impressum