VCS::Lite::Delta(3pm)

💖 VCS::Lite::Delta — the tea on diffs 💖

okay bestie, so this is VCS::Lite::Delta, from the User Contributed Perl Documentation collection. It's the module that handles the differencing side of things — the part of VCS::Lite that stares at two versions of a file and goes "here's exactly what changed, no cap". 🦋

---

✨ 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;

like, that's it. that's the whole vibe. you make two objects, you diff them, you print it. then later you feed a patch back in and get a whole new version out. iconic behaviour, honestly. 🎀

---

🌸 DESCRIPTION 🌸

This module hands you a Delta class that provides the differencing functionality for VCS::Lite. That's the whole job. It diffs. It slays. It does not do your laundry. 💅

---

👑 API 👑

💫 new 💫

okay so the underlying object of VCS::Lite::Delta is literally just an array of difference chunks — hunks — exactly like the kind Algorithm::Diff returns. that's the whole soul of the object. an array of vibes. 🫶

The constructor takes the following forms:

  my $delt = VCS::Lite::Delta->new( '/my/file.diff',$sep); # File name
  my $delt = VCS::Lite::Delta->new( \*FILE,$sep);       # File handle
  my $delt = VCS::Lite::Delta->new( \$string,$sep); # String as scalar ref
  my $delt = VCS::Lite::Delta->new( \@foo, $id1, $id2) # Array ref

$sep here is a regexp — it's the thing you split strings into tokens with. The default is to use the natural perl mechanism of $/, which gets emulated when you're not reading from a file. The arrayref form assumes you're handing it an array of hunks, like the output from Algorithm::Diff::diff.

The other forms assume the input is the text form of a diff listing, either in diff format or in unified format. The input gets parsed, and errors are reported. so if you feed it garbage, it will tell you. 😭

---

🔥 diff 🔥

  print OUTFILE $delt->diff

This generates a standard diff format. for example:

4c4 < Now wherefore stopp'st thou me?  --- > Now wherefore stoppest thou
me?

fr fr, that's the output right there. 🍓

---

🌈 udiff 🌈

  print OUTFILE $delt->udiff

This generates a unified diff — like diff -u — similar to the form in which patches are submitted. iykyk, this is the format all the cool patch emails use. ✨

---

💜 id 💜

  my ($id1,$id2) = $delt->id;
  $delt2->id('foo.pl@@1','foo.pl@@3')

The id method lets you get and set the names associated with the two elements being diffed. For delta objects returned by VCS::Lite->diff, the id gets set to the element IDs of the VCS::Lite objects being diffed. cute, right?

heads up though: diff format omits the file names, so the IDs will not be populated by new. That's not the case with diff -u format — that one includes the file names, which get passed in and are available as IDs. 💀

---

🧚 hunks 🧚

  my @hunklist = $delt->hunks

A hunk is a technical term for a section of input containing a difference. Each hunk is an arrayref, containing the block of lines. And each line is itself an arrayref, for example:

  [
    [ '+', 9, 'use Acme::Foo;'],
    [ '-', 9, 'use Acme::Bar;'],
  ]

See the documentation on Algorithm::Diff for more details of this structure. it's arrays all the way down, bestie. 🪆

---

🦋 SEE ALSO 🦋

• Algorithm::Diff.

---

💀 BUGS, PATCHES & FIXES 💀

There are no known bugs at the time of this release. however — and this is the important bit — if you spot a bug, or you're 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). It would help greatly if you're able to pinpoint problems, or even better, 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-2015

---

🎀 COPYRIGHT 🎀

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

---

💖 LICENCE 💖

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

---

and that's the whole page, bestie!! 🫶 this one shipped as part of perl v5.26.1, dated 2018-04-02 — so go forth and diff responsibly. mwah. 💖✨🌸