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.
API¶
new¶
The underlying storage concept 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.
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, $separation, $source, ...);
- $object_id
- This is a string to identify what is being diffed, patched or merged, in
the application's environment. If there is no $source, this is used as a
filename from which to read the content.
- $separation
- This is an optional parameter, which can be used via $/ to split the input
file into tokens. The default is for lines of text. If you pass in a
string to be tokenized, this will use $sep as a regular expression
$separation can be a scalar or scalar ref, where this is used to break up
the input stream. All values permitted for $/ are allowed (see perlvar).
$separation can also be a hashref, to give a finer level of control. For
example:
{ in => '\n',
out => '\n',
chomp => 1 }
'in' is the input record separator to use (the same as you would pass as
$sep). Note that all values allowed for $/, and indeed the value of $/
passed in is what is used as a default. 'in' can be a string or a regexp.
'out' is the character used on joining the members to output the results
(text method in scalar context). This is the output record separator $\.
Note that 'out' defaults differently depening on the setting of 'chomp':
if 'chomp' is off, 'out' will default to the empty string, or rather the
passed in value of $\. If 'chomp' is on, 'out' will default to 'in' - note
that you should specify 'out' explicitly if you are using a regexp for
'in'.
If the 'chomp' flag is set, the text matching 'in' is removed from the input
lines as they are read. 'chomp' is not on by default, as this is new
functionality in release 0.08.
- $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 $separation
- "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.
apply¶
$lite->apply($lite2);
$lite->apply($lite3, base => 'original');
This method call corresponds approximately to a version control system's
check-in function. This causes $lite to be modified, so that its contents now
reflect those of $lite2.
$lite does retain the original contents, available via original. However, unlike
in a version control system, the object holds only the first original and
latest contents.
The VCS::Lite object passed in can also have its own original version. If this
is the case, merging will be performed to incorporate the change as if it had
come from a different branch. To facilitiate the merging process, optionally
specify a base version, which can be the string 'original', 'contents' (the
default) or a VCS::Lite object whose contents will be used. This corresponds
to the "common ancestor" in version control systems.
original¶
This returns a VCS::Lite object for the original version, before changes were
applied with apply.
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 separation parameter, defaulting to $_, is used to join the strings
together). In list context, returns the list of lines or records.
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.
diff¶
This is for backward compatibility with early versions. $lite->diff($lite2)
is equivalent to $lite->delta($lite2)->diff.
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.
SEE ALSO¶
Algorithm::Diff.
BUGS, PATCHES & FIXES¶
At the time of release there is one known bug within VCS-Lite:
http://rt.cpan.org/Public/Bug/Display.html?id=20738
Unfortunately Ivor's original svn repository is no longer available, and any
work which had done on fixing this bug has now been lost. As time allows I
will review the examples and try to implement an appropriate solution.
If you spot a bug or are experiencing difficulties that are not explained within
the POD documentation, please send an email to barbie@cpan.org or submit a bug
to the RT system (see link below). However, it would help greatly if you are
able to pinpoint problems or even supply a patch.
http://rt.cpan.org/Public/Dist/Display.html?Name=VCS-Lite
Fixes are dependent upon their severity and my availability. Should a fix not be
forthcoming, please feel free to (politely) remind me.
AUTHOR¶
Original Author: Ivor Williams (RIP) 2002-2009
Current Maintainer: Barbie <barbie@cpan.org> 2009-2013
COPYRIGHT¶
Copyright (c) Ivor Williams, 2002-2006
Copyright (c) Barbie, 2009-2013
LICENCE¶
This distribution is free software; you can redistribute it and/or modify it
under the Artistic Licence v2.
ACKNOWLEDGEMENTS¶
Colin Robertson for suggesting and providing patches for support of files with
unterminated last lines.