package VCS::Lite;

use strict;
use warnings;
our $VERSION = '0.01';

=head1 NAME

VCS::Lite - Minimal version control system

=head1 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');
  
=head1 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.

=head2 new

The underlying object of VCS::Lite is an array. The members of the 
array can be anything that a scalar can represent (including reference
+s 
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 B<new> can take.

my $lite = VCS::Lite->new( \@foo);                #Array ref
my $lite = VCS::Lite->new( '/users/me/prog.pl');    #File name
my $lite = VCS::Lite->new( $fh1);                #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.

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

=head2 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) = @_;

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

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

=head1 AUTHOR

I. P. Williams, E<lt>Ivor dot williams (at) tiscali dot co dot United 
+KingdomE<gt>

=head1 SEE ALSO

L<Algorithm::Diff>.

1;
[download]