Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
VCS::Lite(3)	      User Contributed Perl Documentation	  VCS::Lite(3)

       VCS::Lite - Minimal version control system

	 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;

       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.

       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, ...);

	   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.

	   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.

	   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:

	       This is a string	which is tokenized using $separation

	       Array of	tokens

	   "filehandle"	or "globref"
	       Contents	of file	are slurped

	       This is called successively to obtain tokens until received

       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.

	 $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.

       This returns a VCS::Lite	object for the original	version, before
       changes were applied with apply.

	 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

	 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.

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

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

       This is for backward compatibility with early versions.
       $lite->diff($lite2) is equivalent to $lite->delta($lite2)->diff.

	 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.

	 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.


       At the time of release there is one known bug within VCS-Lite:

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

       Fixes are dependent upon	their severity and my availability. Should a
       fix not be forthcoming, please feel free	to (politely) remind me.

	 Original Author: Ivor Williams	(RIP)	       2002-2009
	 Current Maintainer: Barbie <>  2009-2015

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

       This distribution is free software; you can redistribute	it and/or
       modify it under the Artistic Licence v2.

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

perl v5.32.1			  2015-01-17			  VCS::Lite(3)


Want to link to this manual page? Use this URL:

home | help