.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "VCS::Lite 3pm"
.TH VCS::Lite 3pm "2014-02-15" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
VCS::Lite \- Minimal version control system
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use VCS::Lite;
\&
\&  # diff
\&
\&  my $lit = VCS::Lite\->new(\*(Aq/home/me/foo1.txt\*(Aq);
\&  my $lit2 = VCS::Lite\->new(\*(Aq/home/me/foo2.txt\*(Aq);
\&  my $difftxt = $lit\->delta($lit2)\->diff;
\&  print OUTFILE $difftxt;
\&
\&  # patch
\&
\&  my $delt = VCS::Lite::Delta\->new(\*(Aq/home/me/patch.diff\*(Aq);
\&  my $lit3 = $lit\->patch($delt);
\&  print OUTFILE $lit3\->text;
\&
\&  # merge
\&
\&  my $lit4 = $lit\->merge($lit\->delta($lit2),$lit\->delta($lit3));
\&  print OUTFILE $lit4\->text;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
It makes use of the module Algorithm::Diff. It provides the facility
for basic diffing, patching and merging.
.SH "API"
.IX Header "API"
.SS "new"
.IX Subsection "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.
.PP
The basic form of the constructor is as follows:
.PP
.Vb 1
\&  my $lite = VCS::Lite\->new( \*(Aq/my/file\*(Aq);
.Ve
.PP
which slurps the file to make an object. The full form is as follows:
.PP
.Vb 1
\&  my $lite = VCS::Lite\->new( $object_id, $separation, $source, ...);
.Ve
.ie n .IP "$object_id" 4
.el .IP "\f(CW$object_id\fR" 4
.IX Item "$object_id"
This is a string to identify what is being diffed, patched or
merged, in the application's environment. If there is no \f(CW$source\fR, this 
is used as a filename from which to read the content.
.ie n .IP "$separation" 4
.el .IP "\f(CW$separation\fR" 4
.IX Item "$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 \f(CW$sep\fR as a regular expression
.Sp
\&\f(CW$separation\fR 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).
.Sp
\&\f(CW$separation\fR can also be a hashref, to give a finer level of control. For example:
.Sp
.Vb 3
\&  {  in => \*(Aq\en\*(Aq,
\&     out => \*(Aq\en\*(Aq,
\&     chomp => 1 }
.Ve
.Sp
\&'in' is the input record separator to use (the same as you would pass as \f(CW$sep\fR).
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.
.Sp
\&'out' is the character used on joining the members to output the results (text
method in scalar context). This is the output record separator $\e. 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
$\e. If 'chomp' is on, 'out' will default to 'in' \- note that you should 
specify 'out' explicitly if you are using a regexp for 'in'.
.Sp
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.
.ie n .IP "$source" 4
.el .IP "\f(CW$source\fR" 4
.IX Item "$source"
if unspecified causes \f(CW$object_id\fR to be opened as a file and its
entire contents read in. The alternative is to supply \f(CW$source\fR, which can
be one of the following:
.RS 4
.ie n .IP """scalar""" 4
.el .IP "\f(CWscalar\fR" 4
.IX Item "scalar"
This is a string which is tokenized using \f(CW$separation\fR
.ie n .IP """arrayref""" 4
.el .IP "\f(CWarrayref\fR" 4
.IX Item "arrayref"
Array of tokens
.ie n .IP """filehandle"" or ""globref""" 4
.el .IP "\f(CWfilehandle\fR or \f(CWglobref\fR" 4
.IX Item "filehandle or globref"
Contents of file are slurped
.ie n .IP """callback""" 4
.el .IP "\f(CWcallback\fR" 4
.IX Item "callback"
This is called successively to obtain tokens until received undef.
.RE
.RS 4
.RE
.PP
In the Perl spirit of \s-1DWIM,\s0 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 \f(CW$p1\fR, \f(CW$p2\fR, etc. and is
expected to return a scalar which is added (pushed on) to the array.
.SS "apply"
.IX Subsection "apply"
.Vb 2
\&  $lite\->apply($lite2);
\&  $lite\->apply($lite3, base => \*(Aqoriginal\*(Aq);
.Ve
.PP
This method call corresponds approximately to a version control system's
check-in function. This causes \f(CW$lite\fR to be modified, so that its contents
now reflect those of \f(CW$lite2\fR.
.PP
\&\f(CW$lite\fR 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.
.PP
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 \*(L"common ancestor\*(R" in version control systems.
.SS "original"
.IX Subsection "original"
This returns a VCS::Lite object for the original version, before changes were
applied with apply.
.SS "text"
.IX Subsection "text"
.Vb 3
\&  my $foo = $lite\->text;
\&  my $bar = $lit2\->text(\*(Aq|\*(Aq);
\&  my @baz = $lit3\->text;
.Ve
.PP
In scalar context, returns the equivalent of the file contents slurped
(the optional separation parameter, defaulting to \f(CW$_\fR, is used to join
the strings together). In list context, returns the list of lines or
records.
.SS "id"
.IX Subsection "id"
.Vb 1
\&  my $fil = $lite\->id
.Ve
.PP
Returns the name associated with the VCS::Lite element when it was created
by new. This is usually the file name.
.SS "delta"
.IX Subsection "delta"
.Vb 1
\&  my $delt = $lit\->delta($lit2);
.Ve
.PP
Perform the difference between two VCS::Lite objects. This object returns
a VCS::Lite::Delta object.
.SS "diff"
.IX Subsection "diff"
This is for backward compatibility with early versions. \f(CW$lite\fR\->diff($lite2) is 
equivalent to \f(CW$lite\fR\->delta($lite2)\->diff.
.SS "patch"
.IX Subsection "patch"
.Vb 1
\&  my $lit3 = $lit\->patch($delt);
.Ve
.PP
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.
.SS "merge"
.IX Subsection "merge"
.Vb 1
\&  my $lit4 = $lit\->merge($lit1,$lit2,\e&confl);
.Ve
.PP
Performs the \*(L"parallelogram of merging\*(R". This applies two different
change streams represented by VCS::Lite objects. Returns a VCS::Lite
object with both sets of changes merged.
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Algorithm::Diff.
.SH "BUGS, PATCHES & FIXES"
.IX Header "BUGS, PATCHES & FIXES"
At the time of release there is one known bug within VCS-Lite:
.PP
http://rt.cpan.org/Public/Bug/Display.html?id=20738
.PP
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.
.PP
If you spot a bug or are experiencing difficulties that are not explained 
within the \s-1POD\s0 documentation, please send an email to barbie@cpan.org or submit
a bug to the \s-1RT\s0 system (see link below). However, it would help greatly if you 
are able to pinpoint problems or even supply a patch.
.PP
http://rt.cpan.org/Public/Dist/Display.html?Name=VCS\-Lite
.PP
Fixes are dependent upon their severity and my availability. Should a fix not
be forthcoming, please feel free to (politely) remind me.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 2
\&  Original Author: Ivor Williams (RIP)          2002\-2009
\&  Current Maintainer: Barbie <barbie@cpan.org>  2009\-2013
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 2
\&  Copyright (c) Ivor Williams, 2002\-2006
\&  Copyright (c) Barbie,        2009\-2013
.Ve
.SH "LICENCE"
.IX Header "LICENCE"
This distribution is free software; you can redistribute it and/or
modify it under the Artistic Licence v2.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Colin Robertson for suggesting and providing patches for support of
files with unterminated last lines.