.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "File::Modified 3pm" .TH File::Modified 3pm "2015-10-26" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" File::Modified \- checks intelligently if files have changed .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use strict; \& use File::Modified; \& \& my $d = File::Modified\->new(files=>[\*(AqImport.cfg\*(Aq,\*(AqExport.cfg\*(Aq]); \& \& while (1) { \& my (@changes) = $d\->changed; \& \& if (@changes) { \& print "$_ was changed\en" for @changes; \& $d\->update(); \& }; \& sleep 60; \& }; .Ve .PP Second example \- a script that knows when any of its modules have changed : .PP .Vb 2 \& 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(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides a simple mechanism for identifying when the contents of one or more files have changed. It was initially intended for programs to detect when their configuration files (or the module they rely on) have changed. .PP There are currently two methods of change detection implemented, \&\f(CW\*(C`mtime\*(C'\fR and \f(CW\*(C`MD5\*(C'\fR. The \f(CW\*(C`MD5\*(C'\fR method will fall back to use timestamps if the \f(CW\*(C`Digest::MD5\*(C'\fR module cannot be loaded. .PP There are a number of other modules on \s-1CPAN\s0 that provide similar functionality; they are listed in \*(L"\s-1SEE ALSO\*(R"\s0 below. .ie n .IP "new %ARGS" 4 .el .IP "new \f(CW%ARGS\fR" 4 .IX Item "new %ARGS" Creates a new instance. The \f(CW%ARGS\fR hash has two possible keys, \&\f(CW\*(C`Method\*(C'\fR, which denotes the method used for checking as default, and \f(CW\*(C`Files\*(C'\fR, which takes an array reference to the filenames to watch. .IP "add filename, method" 4 .IX Item "add filename, method" Adds a new file to watch. \f(CW\*(C`method\*(C'\fR is the method (or rather, the subclass of \f(CW\*(C`File::Modified::Signature\*(C'\fR) to use to determine whether a file has changed or not. The result is either the \f(CW\*(C`File::Modified::Signature\*(C'\fR subclass or undef if an error occurred. .IP "addfile \s-1LIST\s0" 4 .IX Item "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 \f(CW\*(C`File::Modified::Signature\*(C'\fR subclasses. .IP "update" 4 .IX Item "update" Updates all signatures to the current state. All pending changes are discarded. .IP "changed" 4 .IX Item "changed" Returns a list of the filenames whose files did change since the construction or the last call to \f(CW\*(C`update\*(C'\fR (whichever last occurred). .SS "Signatures" .IX Subsection "Signatures" The module also creates a new namespace \f(CW\*(C`File::Signature\*(C'\fR, 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. .PP The interface is settled, there are two methods, \f(CW\*(C`as_scalar\*(C'\fR and \f(CW\*(C`from_scalar\*(C'\fR, 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 \f(CW\*(C`\en\*(C'\fR or \f(CW\*(C`|\*(C'\fR (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. .PP Currently, I'm planning to use Text::Quote as a quoting mechanism to protect against multiline filenames. .SS "Adding new methods for signatures" .IX Subsection "Adding new methods for signatures" Adding a new signature method is as simple as creating a new subclass of \f(CW\*(C`File::Signature\*(C'\fR. See \f(CW\*(C`File::Signature::Checksum\*(C'\fR for a simple example. There is one point of laziness in the implementation of \f(CW\*(C`File::Signature\*(C'\fR, the \f(CW\*(C`check\*(C'\fR method can only compare strings instead of arbitrary structures (yes, there \s-1ARE\s0 things that are easier in Python than in Perl). \f(CW\*(C`File::Signature::Digest\*(C'\fR is a wrapper for Gisle Aas' Digest module and allows you to use any module below the \f(CW\*(C`Digest\*(C'\fR namespace as a signature, for example \f(CW\*(C`File::Signature::MD5\*(C'\fR and \&\f(CW\*(C`File::Signature::SHA1\*(C'\fR. .SS "\s-1TODO\s0" .IX Subsection "TODO" * Make the simple persistence solution for the signatures better using Text::Quote. .PP * Allow complex structures for the signatures. .PP * Document \f(CW\*(C`File::Modified::Signature\*(C'\fR or put it down into another namespace. .PP * Extract the \f(CW\*(C`File::Modified::Signature\*(C'\fR subclasses out into their own file. .PP * Create an easy option to watch a whole directory tree. .SS "\s-1EXPORT\s0" .IX Subsection "EXPORT" None by default. .SH "SEE ALSO" .IX Header "SEE ALSO" File::Monitor will watch a file or directory, invoking a callback when it changes. .PP File::Monitor::Lite is similar to File::Monitor, but can also let you know about new files being created. .PP File::Monitor::Simple watches a directory for changes to any files whose name matches a regular expression. .PP File::IfModified provides a function that can be used to check whether a file has been modified since the last time you checked. .PP File::ChangeNotify provides an \s-1API\s0 for watching all files in a given directory. It provides several mechanisms for doing this, and a base-class that you can subclass to write your own watcher. .PP File::Signature provides some lower-level functions than File::Modified, which are used to identify whether a file has changed by comparing its \s-1MD5\s0 digest with an earlier snapshot. .PP File::Stat::Trigger will invoke one of your callbacks if the \f(CW\*(C`stat()\*(C'\fR details of a file change. .PP Win32::FileSystem::Watcher provides a Windows-specific solution for watching for changes to a filesystem. The documentation is extremely limited, so I can't tell if you can limit it a specific directory. .PP App::watcher comes with a script that will run a command if any of the files in a directory are changed. .PP IO::Async::File watches an open filehandle or 'named filesystem entity' for changes in its \f(CW\*(C`stat()\*(C'\fR fields. .PP POE::Component::DirWatch watches a directory for new files or directories, invoking a user-supplied callback function when one is seen. .PP WWW::Monitor is similar to File::Monitor, but checks URLs rather than files. .SH "REPOSITORY" .IX Header "REPOSITORY" .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP Copyright (C) 2002 Max Maischein .SH "AUTHOR" .IX Header "AUTHOR" Max Maischein, .PP Please contact me if you find bugs or otherwise improve the module. More tests are also very welcome !