diff --git a/src/lib.rs b/src/lib.rs index 73671e7..3c98cff 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2,6 +2,36 @@ //! interface over different types of diffing algorithms. It's based on the //! the diff algorithm implementations of [pijul](https://pijul.org/). //! +//! The API of the crate is split into high and low level functionality. Most +//! of what you probably want to use is available top level. Additionally the +//! following sub modules exist: +//! +//! * [`algorithms`]: This implements the different types of diffing algorithms. +//! It provides both low level access to the algorithms with the minimal +//! trait bounds necessary, as well as a generic interface. +//! * [`udiff`]: Unified diff functionality. +//! +//! # Sequence Diffing +//! +//! If you want to diff sequences generally indexable things you can use the +//! [`capture_diff`] and [`capture_diff_slices`] functions. They will directly +//! diff an indexable object or slice and return a vector of [`DiffOp`] objects. +//! +//! ```rust +//! use similar::{Algorithm, 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); +//! ``` +//! +//! # Text Diffing +//! +//! Similar provides helpful utilities for text (and more specifically line) diff +//! operations. The main type you want to work with is [`TextDiff`] which +//! uses the underlying diff algorithms to expose a convenient API to work with +//! texts: +//! //! ```rust //! # #[cfg(feature = "text")] { //! use similar::{ChangeTag, TextDiff}; @@ -24,30 +54,6 @@ //! # } //! ``` //! -//! # API -//! -//! The API of the crate is split into high and low level functionality. Most -//! of what you probably want to use is available toplevel. Additionally the -//! following sub modules exist: -//! -//! * [`algorithms`]: This implements the different types of diffing algorithms. -//! It provides both low level access to the algorithms with the minimal -//! trait bounds necessary, as well as a generic interface. -//! * [`udiff`]: Unified diff functionality. -//! -//! # Sequence Diffing -//! -//! If you want to diff sequences generally indexable things you can use the -//! [`capture_diff`] and [`capture_diff_slices`] functions. They will directly -//! diff an indexable object or slice and return a vector of [`DiffOp`] objects. -//! -//! # Text Diffing -//! -//! Similar provides helpful utilities for text (and more specifically line) diff -//! operations. The main type you want to work with is [`TextDiff`] which -//! uses the underlying diff algorithms to expose a convenient API to work with -//! texts. -//! //! ## Trailing Newlines //! //! When working with line diffs (and unified diffs in general) there are two @@ -59,12 +65,15 @@ //! //! In similar this is handled on the [`Change`] or [`InlineChange`] level. If //! a diff was created via [`TextDiff::from_lines`] the text diffing system is -//! instructed to check if there are missing newlines encountered. If that is -//! the case the [`Change`] object will return true from the -//! [`Change::missing_newline`] method so the caller knows to handle this by -//! either rendering a virtual newline at that position or to indicate it in -//! different ways. For instance the unified diff code will render the special -//! `\ No newline at end of file` marker. +//! instructed to check if there are missing newlines encountered +//! ([`TextDiff::newline_terminated`] returns true). +//! +//! In any case the [`Change`] object has a convenience method called +//! [`Change::missing_newline`] which returns `true` if the change is missing +//! a trailing newline. Armed with that information the caller knows to handle +//! this by either rendering a virtual newline at that position or to indicate +//! it in different ways. For instance the unified diff code will render the +//! special `\ No newline at end of file` marker. //! //! ## Bytes vs Unicode //! @@ -118,6 +127,7 @@ //! in a line diff. This currently also enables the `unicode` feature. #![warn(missing_docs)] pub mod algorithms; +#[cfg(feature = "text")] pub mod udiff; mod common; diff --git a/src/text/abstraction.rs b/src/text/abstraction.rs index f23b602..0d4f6c9 100644 --- a/src/text/abstraction.rs +++ b/src/text/abstraction.rs @@ -13,6 +13,8 @@ use std::ops::Range; /// /// This trait is used in the library whenever it's nice to be able to pass /// strings of different types in. +/// +/// Requires the `text` feature. pub trait DiffableStrRef { /// The type of the resolved [`DiffableStr`]. type Output: DiffableStr + ?Sized; @@ -60,6 +62,8 @@ impl DiffableStrRef for Vec { /// on how the crate is compiled. Out of the box `&str` is always supported /// but with the `bytes` feature one can also work with `[u8]` slices for /// as long as they are ASCII compatible. +/// +/// Requires the `text` feature. pub trait DiffableStr: Hash + PartialEq + PartialOrd + Ord + Eq + ToOwned { /// Splits the value into newlines with newlines attached. fn tokenize_lines(&self) -> Vec<&Self>; @@ -217,6 +221,9 @@ impl DiffableStr for str { } } +/// Allows viewing ASCII compatible byte slices as strings. +/// +/// Requires the `bytes` feature. #[cfg(feature = "bytes")] impl DiffableStr for [u8] { fn tokenize_lines(&self) -> Vec<&Self> { diff --git a/src/text/mod.rs b/src/text/mod.rs index 260f28c..8c5e6b7 100644 --- a/src/text/mod.rs +++ b/src/text/mod.rs @@ -17,6 +17,8 @@ use crate::udiff::UnifiedDiff; use crate::{capture_diff_slices, get_diff_ratio, group_diff_ops, Algorithm, Change, DiffOp}; /// A builder type config for more complex uses of [`TextDiff`]. +/// +/// Requires the `text` feature. #[derive(Clone, Debug)] pub struct TextDiffConfig { algorithm: Algorithm, @@ -159,7 +161,9 @@ impl TextDiffConfig { } } -/// Captures diff op codes for textual diffs +/// Captures diff op codes for textual diffs. +/// +/// Requires the `text` feature. pub struct TextDiff<'old, 'new, 'bufs, T: DiffableStr + ?Sized> { old: Cow<'bufs, [&'old T]>, new: Cow<'bufs, [&'new T]>, @@ -333,6 +337,8 @@ impl<'old, 'new, 'bufs, T: DiffableStr + ?Sized + 'old + 'new> TextDiff<'old, 'n /// ); /// assert_eq!(matches, vec!["apple", "ape"]); /// ``` +/// +/// Requires the `text` feature. pub fn get_close_matches<'a, T: DiffableStr + ?Sized>( word: &T, possibilities: &[&'a T],