= diff-lcs

== Description
Diff::LCS is a port of Perl's Algorithm::Diff that uses the McIlroy-Hunt
longest common subsequence (LCS) algorithm to compute intelligent differences
between two sequenced enumerable containers. The implementation is based on
Mario I. Wolczko's {Smalltalk version 1.2}[ftp://st.cs.uiuc.edu/pub/Smalltalk/MANCHESTER/manchester/4.0/diff.st]
(1993) and Ned Konz's Perl version
{Algorithm::Diff 1.15}[http://search.cpan.org/~nedkonz/Algorithm-Diff-1.15/].

This is release 1.1.3, fixing several small bugs found over the years. Version
1.1.0 added new features, including the ability to #patch and #unpatch changes
as well as a new contextual diff callback, Diff::LCS::ContextDiffCallbacks,
that should improve the context sensitivity of patching.

This library is called Diff::LCS because of an early version of Algorithm::Diff
which was restrictively licensed. This version has seen a minor license change:
instead of being under Ruby's license as an option, the third optional license
is the MIT license.

== Where

* {GitHub}[https://github.com/halostatue/diff-lcs]

This is the new home of Diff::LCS (diff-lcs). The Ruwiki page still refers to
it, but development is not happening there any longer.

== Synopsis

Using this module is quite simple. By default, Diff::LCS does not extend
objects with the Diff::LCS interface, but will be called as if it were a
function:

  require 'diff/lcs'

  seq1 = %w(a b c e h j l m n p)
  seq2 = %w(b c d e f j k l m r s t)

  lcs = Diff::LCS.LCS(seq1, seq2)
  diffs = Diff::LCS.diff(seq1, seq2)
  sdiff = Diff::LCS.sdiff(seq1, seq2)
  seq = Diff::LCS.traverse_sequences(seq1, seq2, callback_obj)
  bal = Diff::LCS.traverse_balanced(seq1, seq2, callback_obj)
  seq2 == Diff::LCS.patch!(seq1, diffs)
  seq1 == Diff::LCS.unpatch!(seq2, diffs)
  seq2 == Diff::LCS.patch!(seq1, sdiff)
  seq1 == Diff::LCS.unpatch!(seq2, sdiff)

Objects can be extended with Diff::LCS:

  seq1.extend(Diff::LCS)
  lcs = seq1.lcs(seq2)
  diffs = seq1.diff(seq2)
  sdiff = seq1.sdiff(seq2)
  seq = seq1.traverse_sequences(seq2, callback_obj)
  bal = seq1.traverse_balanced(seq2, callback_obj)
  seq2 == seq1.patch!(diffs)
  seq1 == seq2.unpatch!(diffs)
  seq2 == seq1.patch!(sdiff)
  seq1 == seq2.unpatch!(sdiff)

By requiring 'diff/lcs/array' or 'diff/lcs/string', Array or String will be
extended for use this way.

Note that Diff::LCS requires a sequenced enumerable container, which means that
the order of enumeration is both predictable and consistent for the same set of
data. While it is theoretically possible to generate a diff for unordereded
hash, it will only be meaningful if the enumeration of the hashes is
consistent. In general, this will mean that containers that behave like String
or Array will perform best.

:include: License.rdoc
