VCS::Lite(3pm)						User Contributed Perl Documentation					    VCS::Lite(3pm)

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 => '
',
		out => '
',
		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.

   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.

   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.

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 dependant upon their severity and my availablity. Should a fix not be forthcoming, please feel free to (politely) remind me.

AUTHOR

	 Original Author: Ivor Williams (RIP)	       2008-2009
	 Current Maintainer: Barbie <barbie@cpan.org>  2009

COPYRIGHT

	 Copyright (c) Ivor Williams, 2002-2006
	 Copyright (c) Barbie,	      2009

LICENCE

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

ACKNOWLEDGEMENTS

       Colin Robertson for suggesting and providing patches for support of files with unterminated last lines.

SEE ALSO

       Algorithm::Diff.

perl v5.10.1							    2009-10-25							    VCS::Lite(3pm)