NAME

File::Repl - Perl module that provides file replication utilities

SYNOPSIS

use File::Repl;

%con = {
  dira     => 'C:/perl',
  dirb     => 'M:/perl',
  verbose  => '1',
  age      => '10',
};

$ref=File::Repl->New(\%con);
$ref->Update('\.p(l|m)','a<>b',1);
$ref->Update('\.t.*','a<>b',1,'\.tmp$');

DESCRIPTION

The File:Repl provides simple file replication and management utilities. Its main functions are

File Replication

Allowing two directory structures to be maintained, ensuring files that meet selection logic criteria are mirrored and otherwise synchronized.

Bulk Renaming

Allowing files in a directory structure to be renamed according to the selection logic.

Compressing

Allowing files in a directory structure to be compressed according to a given logic.

Process

Run a common perl process against files in a directory structure according to selection logic.

Deletion

Allowing files in a directory structure to be deleted according to the selection logic.

METHODS

New(%con)

The New method constructs a new File-Repl object. Options are passed in the form of a hash reference \%con which define the file directories to be operated on and other parameters. The directories are scanned and each file is stat'ed. The hash keys have the following definitions-

dira

This identifies the first directory to be scanned (required).

dirb

This identifies the second directory to be scanned (required). If the object is only to have methods operate on it that operate on a single directory then dirb can be set to the same value as dira. This minimizes the directory structure to be sesarched.

verbose

The verbose flag has several valid values:

0

No verbosity (default mode).

1

All file copies and deletes are printed.

2

Tombstone file trunkations are printed, and any timestamp changes made,

3

Configuration settings (from %con) and Files meeting the match criteria are printed.

4

Files identified in each directory that match the regex requirements (from the Update method) are printed.

age

This specifies the maximum age of a file in days. Files older than this will be ignored by Update, Rename, Compress and Delete methods.

recurse

When set to FALSE only files at the top level of the dira and dirb are scanned. Default value is

ttl

This is the time to live (ttl for any tombstoned file, in days. Default value is 31.

nocase

Switches for case sensitivity - default is TRUE (case insensitive).

mkdirs

If either directory dira or dirb do not exist will attempt to create the directory if set TRUE. Default value is FALSE.

Update(regex, [noregex,] action, commit)

The Update method makes the file updates requested - determined by the %con hash (from the New method) and four associated arguments.

This method also allows files to be tombstoned (ie removed from the replicated file sets). A file is tombstoned by appending .remove to the file name. The first Update will cause the file to be set to zero size, and any replica files to be renamed (so the original file does not return). The next update after the ttl has expired will cause deletion of all file replicas.

If a directory is tombstoned (by adding .remove to its name) the directory and contents are removed and a file with the directory name and the .remove suffix replaces it. The file is removed as a normally tombstoned file.

regex

A regular expression, used to match all file names that are to be maintained.

noregex

An optional regular expression used to match all files not to be maintained (ie excluded from the operation).

action

defines the action to be performed.

a>b

Files in the 'a' directory are to be replicated to the 'b' directory if a replica exists in 'b' directory and the timestamp is older than that of the file in the 'a' directory.

a<b

Files in the 'b' directory are to be replicated to the 'a' directory if a replica exists in 'a' directory and the timestamp is older than that of the file in the 'b' directory.

a<>b

Files in the 'a' directory are to be replicated to the 'b' directory if a replica exists in 'b' directory and the timestamp is older than that of the file in the 'a' directory. Files in the 'b' directory are to be replicated to the 'a' directory if a replica exists in 'a' directory and the timestamp is older than that of the file in the 'b' directory.

A>B

Files in the 'a' directory are to be replicated to the 'b' directory - even if no replica exists in 'b' directory. If a replica already exists in the 'b' directory with a timestamp that is newer than that of the file in the 'a' directory it is not modified.

A>B!

Files in the 'a' directory are to be replicated to the 'b' directory - even if no replica exists in 'b' directory. If a replica already exists in the 'b' directory with a timestamp that is newer than that of the file in the 'a' directory it is not modified. Orphan files in the 'b' directory are deleted.

A<B

Files in the 'b' directory are to be replicated to the 'a' directory - even if no replica exists in 'a' directory. If a replica already exists in the 'a' directory with a timestamp that is newer than that of the file in the 'b' directory it is not modified.

A<B!

Files in the 'b' directory are to be replicated to the 'a' directory - even if no replica exists in 'a' directory. If a replica already exists in the 'a' directory with a timestamp that is newer than that of the file in the 'b' directory it is not modified. Orphan files in the 'a' directory are deleted.

A<>B

Files in the 'a' directory are to be replicated to the 'b' directory - even if no replica exists in 'b' directory. If a replica already exists in the 'b' directory with a timestamp that is newer than that of the file in the 'a' directory it is not modified. Files in the 'b' directory are to be replicated to the 'a' directory - even if no replica exists in 'a' directory. If a replica already exists in the 'a' directory with a timestamp that is newer than that of the file in the 'b' directory it is not modified.

commit

When set TRUE makes changes required - set FALSE to show potential changes (which are printed to STDOUT)

Rename(regex, [noregex], namesub, commit)

The Rename method is used to rename files in the dira directory structure in the object specified in the New method.

regex

A regular expression, used to match all file names that are to be renamed.

noregex

An optional regular expression used to match all files not to be renamed (ie excluded from the operation).

namesub

The argument used for a perl substitution command is applied to the file name to create the file's new name.

e.g. /\.pl$/\.perl\$/

This examplewill rename all files (that meet regex and noregex criteria) from .pl to .perl

commit

When set TRUE makes renames required - set FALSE to show potential changes (which are printed to STDOUT)

Process

Not yet implemeneted

Compress

Not yet implemented

Delete(regex, [noregex], commit)

The Delete method removes files from the dira directory structure in the object specified in the New method.

regex

A regular expression, used to match all file names that are to be deleted.

noregex

An optional regular expression used to match all files not to be deleted (ie excluded from the operation).

commit

When set TRUE makes deletions required - set FALSE to show potential changes (which are printed to STDOUT)

REQUIRED MODULES

File::Find;
File::Copy;
File::Basename;

Win32::AdminMisc (Win32 platforms only)
Win32::API       (Win32 platforms only)

TIMEZONE AND FILESYSTEMS

On FAT filesystems, mtime resolution is 1/30th of a second. A fudge of 2 seconds is used for synching FAT with other filesystems. Note that FAT filesystems save the local time in UTC (GMT).

On FAT filesystems, "stat" adds TZ_BIAS to the actual file times (atime, ctime and mtime) and conversley "utime" subtracts TZ_BIAS from the supplied parameters before setting file times. To maintain FAT at UTC time, we need to do the opposite.

If we don't maintain FAT filesystems at UTC time and the repl is between FAT and NON-FAT systems, then all files will get replicated whenever the TZ or Daylight Savings Time changes.

AUTHOR

Dave Roberts

SUPPORT

You can send bug reports and suggestions for improvements on this module to me at DaveRoberts@iname.com. However, I can't promise to offer any other support for this script.

COPYRIGHT

This module is Copyright © 2000, 2001 Dave Roberts. All rights reserved.

This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This script is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. The copyright holder of this script can not be held liable for any general, special, incidental or consequential damages arising out of the use of the script.

CHANGE HISTORY

$Log: repl.pm $ Revision 1.10 2001/07/06 08:23:48 Dave.Roberts code changes to allow the colume info to be detected correctly using Win32::AdminMisc when a drive letter is specified (was only working with UNC names)

Revision 1.9 2001/06/27 13:35:53 Dave.Roberts minor presentation changes

Revision 1.8 2001/06/27 12:59:22 jj768 logic to prevent "Use of uninitialized value in pattern match (m//)" errors on use of $vol{FileSystemName}

Revision 1.6 2001/06/21 12:32:15 jj768

*** empty log message ***

Revision 1.5 2001/06/20 20:39:21 Dave.Roberts minor header changes

Revision 1.4 2001/06/20 19:55:21 jj768 re-built module source files as per perlmodnew manpage

Revision 1.1 2001/06/20 19:53:03 Dave.Roberts Initial revision

Revision 1.3.5.0 2001/06/19 10:34:11 jj768 Revised calling of the New method to use a hash reference, rather than a hash directly

Revision 1.3.4.0 2001/06/19 09:48:38 jj768 intermediate development revision. Introduced Delete method and the _generic subroutine (used for all methods except New) this is preparatory to the hash being passed as a reference

Revision 1.3.3.0 2001/06/14 15:42:48 jj768 minor code changes in constructing hash and improvement in documentation -still need more docs on Timezones.

cpanm File::Repl

perl -MCPAN -e shell
install File::Repl