Better split functionality between toplevel and algorithms

src/algorithms/capture.rs

@@ -1,6 +1,7 @@
 use std::convert::Infallible;
 
-use crate::{group_diff_ops, DiffHook, DiffOp};
+use crate::algorithms::DiffHook;
+use crate::{group_diff_ops, DiffOp};
 
 /// A [`DiffHook`] that captures all diff operations.
 #[derive(Default, Clone)]

src/algorithms/hook.rs

@@ -0,0 +1,109 @@
+/// A trait for reacting to an edit script from the "old" version to
+/// the "new" version.
+pub trait DiffHook: Sized {
+    /// The error produced from the hook methods.
+    type Error;
+
+    /// Called when lines with indices `old_index` (in the old version) and
+    /// `new_index` (in the new version) start an section equal in both
+    /// versions, of length `len`.
+    fn equal(&mut self, old_index: usize, new_index: usize, len: usize) -> Result<(), Self::Error> {
+        let _ = old_index;
+        let _ = new_index;
+        let _ = len;
+        Ok(())
+    }
+
+    /// Called when a section of length `old_len`, starting at `old_index`,
+    /// needs to be deleted from the old version.
+    fn delete(
+        &mut self,
+        old_index: usize,
+        old_len: usize,
+        new_index: usize,
+    ) -> Result<(), Self::Error> {
+        let _ = old_index;
+        let _ = old_len;
+        let _ = new_index;
+        Ok(())
+    }
+
+    /// Called when a section of the new version, of length `new_len`
+    /// and starting at `new_index`, needs to be inserted at position `old_index'.
+    fn insert(
+        &mut self,
+        old_index: usize,
+        new_index: usize,
+        new_len: usize,
+    ) -> Result<(), Self::Error> {
+        let _ = old_index;
+        let _ = new_index;
+        let _ = new_len;
+        Ok(())
+    }
+
+    /// Called when a section of the old version, starting at index
+    /// `old_index` and of length `old_len`, needs to be replaced with a
+    /// section of length `new_len`, starting at `new_index`, of the new
+    /// version.
+    ///
+    /// The default implementations invokes `delete` and `insert`.
+    ///
+    /// You can use the [`Replace`](crate::algorithms::Replace) hook to
+    /// automatically generate these.
+    fn replace(
+        &mut self,
+        old_index: usize,
+        old_len: usize,
+        new_index: usize,
+        new_len: usize,
+    ) -> Result<(), Self::Error> {
+        self.delete(old_index, old_len, new_index)?;
+        self.insert(old_index, new_index, new_len)
+    }
+
+    /// Always called at the end of the algorithm.
+    fn finish(&mut self) -> Result<(), Self::Error> {
+        Ok(())
+    }
+}
+
+impl<'a, D: DiffHook + 'a> DiffHook for &'a mut D {
+    type Error = D::Error;
+
+    fn equal(&mut self, old_index: usize, new_index: usize, len: usize) -> Result<(), Self::Error> {
+        (*self).equal(old_index, new_index, len)
+    }
+
+    fn delete(
+        &mut self,
+        old_index: usize,
+        old_len: usize,
+        new_index: usize,
+    ) -> Result<(), Self::Error> {
+        (*self).delete(old_index, old_len, new_index)
+    }
+
+    fn insert(
+        &mut self,
+        old_index: usize,
+        new_index: usize,
+        new_len: usize,
+    ) -> Result<(), Self::Error> {
+        (*self).insert(old_index, new_index, new_len)
+    }
+
+    fn replace(
+        &mut self,
+        old: usize,
+        old_len: usize,
+        new: usize,
+        new_len: usize,
+    ) -> Result<(), Self::Error> {
+        (*self).replace(old, old_len, new, new_len)
+    }
+
+    fn finish(&mut self) -> Result<(), Self::Error> {
+        (*self).finish()
+    }
+}

src/algorithms/mod.rs

@@ -6,14 +6,14 @@
 //! direct access to these algorithms can be useful in some cases.
 //!
 //! All these algorithms provide a `diff` function which takes two indexable
-//! objects (for instance slices) and a [`DiffHook`](crate::DiffHook).  As the
+//! objects (for instance slices) and a [`DiffHook`].  As the
 //! diff is generated the diff hook is invoked.  Note that the diff hook does
 //! not get access to the actual values but only the indexes.  This is why the
 //! diff hook is not used outside of the raw algorithm implementations as for
 //! most situations access to the values is useful of required.
 //!
-//! A more generic interface for these algorthms is available on the toplevel
-//! module.
+//! The algoriths module really is the most low-level module in similar and
+//! generally not the place to start.
 //!
 //! # Example
 //!
@@ -21,18 +21,64 @@
 //! between two sequences and capture the ops into a vector.
 //!
 //! ```rust
-//! use similar::{Algorithm, capture_diff_slices};
+//! use similar::algorithms::{Algorithm, Replace, Capture, diff_slices};
 //!
 //! let a = vec![1, 2, 3, 4, 5];
 //! let b = vec![1, 2, 3, 4, 7];
-//! let ops = capture_diff_slices(Algorithm::Myers, &a, &b);
+//! let mut d = Replace::new(Capture::new());
+//! diff_slices(Algorithm::Myers, &mut d, &a, &b).unwrap();
+//! let ops = d.into_inner().into_ops();
 //! ```
+//!
+//! The above example is equivalen to using
+//! [`capture_diff_slices`](crate::capture_diff_slices).
 
 mod capture;
+mod hook;
 mod replace;
 
+use std::hash::Hash;
+use std::ops::{Index, Range};
+
 pub use capture::Capture;
+pub use hook::DiffHook;
 pub use replace::Replace;
 
+#[doc(no_inline)]
+pub use crate::Algorithm;
+
 pub mod myers;
 pub mod patience;
+
+/// Creates a diff between old and new with the given algorithm.
+///
+/// Diffs `old`, between indices `old_range` and `new` between indices `new_range`.
+pub fn diff<Old, New, D>(
+    alg: Algorithm,
+    d: &mut D,
+    old: &Old,
+    old_range: Range<usize>,
+    new: &New,
+    new_range: Range<usize>,
+) -> Result<(), D::Error>
+where
+    Old: Index<usize> + ?Sized,
+    New: Index<usize> + ?Sized,
+    D: DiffHook,
+    Old::Output: Hash + Eq + Ord,
+    New::Output: PartialEq<Old::Output> + Hash + Eq + Ord,
+{
+    match alg {
+        Algorithm::Myers => myers::diff(d, old, old_range, new, new_range),
+        Algorithm::Patience => patience::diff(d, old, old_range, new, new_range),
+    }
+}
+
+/// Shortcut for diffing slices with a specific algorithm.
+pub fn diff_slices<D, T>(alg: Algorithm, d: &mut D, old: &[T], new: &[T]) -> Result<(), D::Error>
+where
+    D: DiffHook,
+    T: Eq + Hash + Ord,
+{
+    diff(alg, d, old, 0..old.len(), new, 0..new.len())
+}

src/algorithms/myers.rs

@@ -9,7 +9,7 @@
 use std::cmp::{max, min};
 use std::ops::{Index, Range};
 
-use crate::DiffHook;
+use crate::algorithms::DiffHook;
 
 /// Myers' diff algorithm.
 ///

src/algorithms/patience.rs

@@ -10,8 +10,7 @@ use std::collections::HashMap;
 use std::hash::Hash;
 use std::ops::{Index, Range};
 
-use crate::algorithms::{myers, Replace};
-use crate::DiffHook;
+use crate::algorithms::{myers, DiffHook, Replace};
 
 /// Patience diff algorithm.
 ///

src/algorithms/replace.rs

@@ -1,4 +1,4 @@
-use crate::DiffHook;
+use crate::algorithms::DiffHook;
 
 /// A [`DiffHook`] that combines deletions and insertions to give blocks
 /// of maximal length, and replacements when appropriate.