File::Revision 0.03

File::Revision is a Perl module to return a name of non-existing backup file with a revision id.

SYNOPSIS

#######
# Subroutine interface
#
use File::Revision qw(new_revision num2revision parse_options revision2num revision_file rotate);

($file_name, $next_revsion) = new_revision($file, @options);
($file_name, $next_revsion) = new_revision($file, @options);
($file_name, $next_revsion) = new_revision($file, %options);

$revision_letter = num2revision($revision_number);

$options = parse_options($file, @options);
$options = parse_options($file, @options);
$options = parse_options($file, %options);

$revision_number = revision2num($revision_letter;

$file_name = revision_file($revision_number, $options);

$file_name = rotate($file, @options);
$file_name = rotate($file, @options);
$file_name = rotate($file, %options);

#######
# Object interface
#
$self = File::Revision; # or
$self = new $class; # where $class::@ISA contains File::Revision

($file_name, $next_revsion) = $self->new_revision($file, @options);
($file_name, $next_revsion) = $self->new_revision($file, @options);
($file_name, $next_revsion) = $self->new_revision($file, %options);

$revision_letter = $self->num2revision($revision_number);

$options = $self->parse_options($file, @options);
$options = $self->parse_options($file, @options);
$options = $self->parse_options($file, %options);

$revision_number = $self->revision2num($revision_letter;

$file_name = $self->revision_file($revision_number, $options);

$file_name = $self->rotate($file, @options);
$file_name = $self->rotate($file, @options);
$file_name = $self->rotate($file, %options);

The File::Revision program modules provides the name of a non-existing file with a revision identifier based on the a file name $file. This has many uses backup file uses. There are no restrictions on the number of backup files or the time to live of the backup files.

A typical use would be to create a backup file for If the revised file passes does not pass all validity checks, use the backup file to replace or repair the revised file. This minimizes loses import data when revising files.

Better yet, create a temporary file, using one of the temp file name program modules. Revise the temp file. Once it passes all valitity checks, rename the original file to the backup file and rename the temp file to the original file. This allows full use of the original file until a validated revison is ready to replace it.

The File::Revision program module also supports limiting the backup files and delete the oldest once File::Revision reaches the rotation limit.