/ 
VCS-Lite-0.06
River stage one • 4 direct dependents • 7 total dependents
/ VCS::Lite

NAME

VCS::Lite - Minimal version control system

SYNOPSIS

use VCS::Lite;

# diff

my $lit = VCS::Lite->new('/home/me/foo1.txt');
my $lit2 = VCS::Lite->new('/home/me/foo2.txt');
my $difftxt = $lit->delta($lit2)->diff;
print OUTFILE $difftxt;

# patch

my $delt = VCS::Lite::Delta->new('/home/me/patch.diff');
my $lit3 = $lit->patch($delt);
print OUTFILE $lit3->text;

# merge

my $lit4 = $lit->merge($lit->delta($lit2),$lit->delta($lit3));
print OUTFILE $lit4->text;

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,

The basic form of the constructor is as follows:

my $lite = VCS::Lite->new( '/my/file');

which slurps the file to make an object. The full form is as follows:

my $lite = VCS::Lite->new( $object_id, $separator, $source, ...);

$object_id here is a string to identify what is being diffed, patched or merged, in the application's environment.

$separator here is a regexp by which to split strings into tokens. The default is to use the natural perl mechanism of $/ (which is emulated when not reading from a file). The resulting VCS::Lite objects are unchomped by default.

$source if unspecified causes $object_id to be opened as a file and its entire contents read in. The alternative is to supply $source, which can be one of the following:

scalar - This is a string which is tokenized using $separator
arrayref - Array of tokens
filehandle or globref - contents of file are slurped
callback - This is called successively to obtain tokens until received undef.

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.

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, defaulting to $_, is used to join the strings together). In list context, returns the list of lines or records.

id

my $fil = $lite->id

Returns the name associated with the VCS::Lite element when it was created by new. This is usually the file name.

delta

my $delt = $lit->delta($lit2);

Perform the difference between two VCS::Lite objects. This object returns a VCS::Lite::Delta object.

patch

my $lit3 = $lit->patch($delt);

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($lit1,$lit2,\&confl);

Performs the "parallelogram of merging". This applies two different change streams represented by VCS::Lite objects. 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.

COPYRIGHT

Copyright (c) Ivor Williams, 2002-2005

LICENCE

You may use, modify and distribute this module under the same terms as Perl itself.

SEE ALSO

Algorithm::Diff.