NAME

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


SYNOPSIS

  use File::Repl;
  %con = (
     'dira',      'D:/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 %con which define the file directories to be operated on. The directories are scanned and each file is stat'ed. The hash keys have the following definition.
dira
This identifies the first directory to be scanned (required).

dirb
This identifies the second directory to be scanned (required).

verbose
The verbose flag has several valid values:
  1. No verbosity (default mode).

  2. All file copies and deletes are printed.

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

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

  5. 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.

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
Not yet implemented.

Process
Not yet implemeneted

Compress
Not yet implemented

Delete
Not yet implemented


TIMEZONE AND FILESYSTEMS

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


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.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.