File::Modified(3pm)

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       The Modified module is intended as a simple method for programs to
35       detect whether configuration files (or modules they rely on) have
36       changed. There are currently two methods of change detection imple‐
37       mented, "mtime" and "MD5".  The "MD5" method will fall back to use
38       timestamps if the "Digest::MD5" module cannot be loaded.
39
40       There is another module, File::Signature, which has many similar fea‐
41       tures, so if this module doesn't do what you need, maybe File::Signa‐
42       ture does. There also is quite some overlap between the two modules,
43       code wise.
44
45       new %ARGS
46           Creates a new instance. The %ARGS hash has two possible keys,
47           "Method", which denotes the method used for checking as default,
48           and "Files", which takes an array reference to the filenames to
49           watch.
50
51       add filename, method
52           Adds a new file to watch. "method" is the method (or rather, the
53           subclass of "File::Modified::Signature") to use to determine
54           whether a file has changed or not. The result is either the
55           "File::Modified::Signature" subclass or undef if an error occurred.
56
57       addfile LIST
58           Adds a list of files to watch. The method used for watching is the
59           default method as set in the constructor. The result is a list of
60           "File::Modified::Signature" subclasses.
61
62       update
63           Updates all signatures to the current state. All pending changes
64           are discarded.
65
66       changed
67           Returns a list of the filenames whose files did change since the
68           construction or the last call to "update" (whichever last
69           occurred).
70
71       Signatures
72
73       The module also creates a new namespace "File::Signature", which some‐
74       time will evolve into its own module in its own file. A file signature
75       is most likely of little interest to you; the only time you might want
76       to access the signature directly is to store the signature in a file
77       for persistence and easy comparision whether an index database is cur‐
78       rent 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
94       Adding a new signature method is as simple as creating a new subclass
95       of "File::Signature". See "File::Signature::Checksum" for a simple
96       example. There is one point of laziness in the implementation of
97       "File::Signature", the "check" method can only compare strings instead
98       of arbitrary structures (yes, there ARE things that are easier in
99       Python than in Perl). "File::Signature::Digest" is a wrapper for Gisle
100       Aas' Digest module and allows you to use any module below the "Digest"
101       namespace as a signature, for example "File::Signature::MD5" and
102       "File::Signature::SHA1".
103
104       TODO
105
106       * Make the simple persistence solution for the signatures better using
107       Text::Quote.
108
109       * Allow complex structures for the signatures.
110
111       * Document "File::Modified::Signature" or put it down into another
112       namespace.
113
114       * Extract the "File::Modified::Signature" subclasses out into their own
115       file.
116
117       * Create an easy option to watch a whole directory tree.
118
119       EXPORT
120
121       None by default.
122
123       COPYRIGHT AND LICENSE
124
125       This library is free software; you can redistribute it and/or modify it
126       under the same terms as Perl itself.
127
128       Copyright (C) 2002 Max Maischein
129

AUTHOR

131       Max Maischein, <corion@cpan.org>
132
133       Please contact me if you find bugs or otherwise improve the module.
134       More tests are also very welcome !
135

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

SEE ALSO