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

src/common.rs

@@ -1,41 +1,8 @@
 use std::hash::Hash;
 use std::ops::{Index, Range};
 
-use crate::algorithms::{myers, patience, Capture, Replace};
-use crate::{Algorithm, DiffHook, DiffOp};
-
-/// 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())
-}
+use crate::algorithms::{diff, diff_slices, Capture, Replace};
+use crate::{Algorithm, DiffOp};
 
 /// Creates a diff between old and new with the given algorithm capturing the ops.
 ///

src/lib.rs

@@ -57,8 +57,6 @@ pub mod algorithms;
 pub mod text;
 
 mod common;
-mod hook;
 mod types;
 pub use self::common::*;
-pub use self::hook::*;
 pub use self::types::*;

src/types.rs

@@ -1,7 +1,7 @@
 use std::fmt;
 use std::ops::{Index, Range};
 
-use crate::hook::DiffHook;
+use crate::algorithms::DiffHook;
 
 /// An enum representing a diffing algorithm.
 #[derive(Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord, Debug)]