NAME
VCS::Lite - Minimal version control system
SYNOPSIS
use VCS::Lite;
# diff
my $lit = VCS::Lite->new($fh1);
my $lit2 = VCS::Lite->new($fh2);
my $difftxt = $lit->diff($lit2);
print OUTFILE $difftxt;
# patch
my $lit3 = $lit->patch($fh3);
$lit3->save('~me/patched_file');
# merge
my $lit4 = $lit->merge($lit2,$lit3);
$lit4->save('~me/merged_file');DESCRIPTION
This module provides the functions normally associated with a version control system, but without needing or implementing a version control system. Applications include wikis, document management systems and configuration management.
It makes use of the module Algorithm::Diff. It provides the facility for basic diffing, patching and merging.
new
The underlying object of VCS::Lite is an array. The members of the array can be anything that a scalar can represent (including references to structures and objects). The default is for the object to hold an array of scalars as strings corresponding to lines of text. If you want other underlying types, it is normal to subclass VCS::Lite for reasons which will become apparent,
There are several forms of the parameter list that new can take.
my $lite = VCS::Lite->new( \@foo); #Array ref my $lite = VCS::Lite->new( '/users/me/prog.pl',$sep); #File name my $lite = VCS::Lite->new( $fh1,$sep); #File handle my $lite = VCS::Lite->new( \&next, $p1, $p2...); #Callback
In the Perl spirit of DWIM, new assumes that given an arrayref, you have already done all the work of making your list of whatevers. Given a string (filename) or a file handle, the file is slurped, reading each line of text into a member of the array. Given a callback, the routine is called successively with arguments $p1, $p2, etc. and is expected to return a scalar which is added (pushed on) to the array. $sep is an optional input record separator regexp - the default is to use $/.
text
my $foo = $lite->text; my $bar = $lit2->text('|'); my @baz = $lit3->text
In scalar context, returns the equivalent of the file contents slurped (the optional separator parameter is used to join the strings together). In list context, returns the list of lines or records.
save
$lit3->save('~me/patched_file');
Save is the reverse operation to new, given a file name or file handle. The file is written out calling the object's serialize method for successive members. If you are subclassing, you can supply your own serializer.
diff
my $difftxt = $lit->diff($lit2);
Perform the difference between two VCS::Lite objects.
Output is in ordinary diff format, e.g.:
827c828 < my ($id, $name) = @_; --- > my ($id, $name, $prefix) = @_;
patch
my $lit3 = $lit->patch($fh3);
Applies a patch to a VCS::Lite object. Accepts a file handle or file name string. Reads the file in diff format, and applies it. Returns a VCS::Lite object for the patched source.
merge
my $lit4 = $lit->merge($lit2,$lit3,\&confl);
Performs the "parallelogram of merging". This takes three VCS::Lite objects - the base object and two change streams. Returns a VCS::Lite object with both sets of changes merged.
The third parameter to the method is a sub which is called whenever a merge conflict occurs. This needs to either resolve the conflict or insert the necessary text to highlight the conflict.
AUTHOR
I. P. Williams, <Ivor dot williams (at) tiscali dot co dot United Kingdom>