- Make the diff enums drop useless allocations

- Change the API to hand throught serde_jsons Values
- Add better README.md
- Bump version
- Add better docs

Author: ChrisRega

Cargo.toml

@@ -1,23 +1,23 @@
 [package]
 name = "json_diff_ng"
-version = "0.6.0-RC2"
+version = "0.6.0-RC3"
 authors = ["ksceriath", "ChrisRega"]
 edition = "2021"
 license = "Unlicense"
-description = "A small diff tool utility for comparing jsons. Forked from ksceriath and improved for usage as a library and with proper support for array diffs."
+description = "A JSON diff library and CLI."
 readme = "README.md"
 homepage = "https://github.com/ChrisRega/json-diff"
 repository = "https://github.com/ChrisRega/json-diff"
 keywords = ["cli", "diff", "json"]
 categories = ["command-line-utilities"]
 
 [lib]
-name = "json_diff"
+name = "json_diff_ng"
 path = "src/lib.rs"
 crate-type = ["lib"]
 
 [[bin]]
-name = "json_diff"
+name = "json_diff_ng"
 path = "src/main.rs"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

README.md

@@ -1,5 +1,38 @@
-# json-diff
+# json-diff-ng
 
+[![Crates.io](https://img.shields.io/crates/d/json_diff_ng?style=flat)](https://crates.io/crates/json_diff_ng)
+[![Documentation](https://docs.rs/json_diff_ng/badge.svg)](https://docs.rs/json_diff_ng)
+![CI](https://github.com/ChrisRega/json-diff/actions/workflows/rust.yml/badge.svg?branch=master "CI")
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat)](LICENSE)
+
+## Contributors:
+
+<a href="https://github.com/ChrisRega/json-diff/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=ChrisRega/json-diff"  alt="Contributors"/>
+</a>
+
+## Library
+json_diff_ng can be used to get diffs of json-serializable structures in rust.
+
+### Usage example
+```rust
+use json_diff::compare_strs;
+let data1 = r#"["a",{"c": ["d","f"] },"b"]"#;
+let data2 = r#"["b",{"c": ["e","d"] },"a"]"#;
+let diffs = compare_strs(data1, data2, true, &[]).unwrap();
+assert!(!diffs.is_empty());
+let diffs = diffs.unequal_values.get_diffs();
+assert_eq!(diffs.len(), 1);
+assert_eq!(
+  diffs.first().unwrap().to_string(),
+  r#".[0].c.[1].("f" != "e")"#
+);
+```
+
+See [docs.rs](https://docs.rs/json_diff_ng) for more details.
+
+
+## CLI
 json-diff is a command line utility to compare two jsons.  
 
 Input can be fed as inline strings or through files.  
@@ -17,9 +50,5 @@ file   :   read input from json files
 direct   :   read input from command line
 
 ### Installation
+`$ cargo install json_diff_ng`
 
-Currently, json-diff is available through crates.io (apart from building this repo directly). For crate installation,  
-* Install cargo, through rustup  
-`$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`  
-* Install json-diff  
-`$ cargo install json_diff`

src/ds/key_node.rs

@@ -5,23 +5,27 @@ use serde_json::Value;
 use crate::enums::{DiffEntry, PathElement};
 
 #[derive(Debug, PartialEq)]
-pub enum TreeNode {
+pub enum DiffTreeNode {
     Null,
     Value(Value, Value),
-    Node(HashMap<String, TreeNode>),
-    Array(Vec<(usize, TreeNode)>),
+    Node(HashMap<String, DiffTreeNode>),
+    Array(Vec<(usize, DiffTreeNode)>),
 }
 
-impl TreeNode {
-    pub fn get_diffs(&self) -> Vec<DiffEntry> {
+impl<'a> DiffTreeNode {
+    pub fn get_diffs(&'a self) -> Vec<DiffEntry<'a>> {
         let mut buf = Vec::new();
         self.follow_path(&mut buf, &[]);
         buf
     }
 
-    pub fn follow_path(&self, diffs: &mut Vec<DiffEntry>, offset: &[PathElement]) {
+    pub fn follow_path<'b>(
+        &'a self,
+        diffs: &mut Vec<DiffEntry<'a>>,
+        offset: &'b [PathElement<'a>],
+    ) {
         match self {
-            TreeNode::Null => {
+            DiffTreeNode::Null => {
                 let is_map_child = offset
                     .last()
                     .map(|o| matches!(o, PathElement::Object(_)))
@@ -33,18 +37,18 @@ impl TreeNode {
                     });
                 }
             }
-            TreeNode::Value(l, r) => diffs.push(DiffEntry {
+            DiffTreeNode::Value(l, r) => diffs.push(DiffEntry {
                 path: offset.to_vec(),
-                values: Some((l.to_string(), r.to_string())),
+                values: Some((l, r)),
             }),
-            TreeNode::Node(o) => {
+            DiffTreeNode::Node(o) => {
                 for (k, v) in o {
                     let mut new_offset = offset.to_vec();
-                    new_offset.push(PathElement::Object(k.clone()));
+                    new_offset.push(PathElement::Object(k));
                     v.follow_path(diffs, &new_offset);
                 }
             }
-            TreeNode::Array(v) => {
+            DiffTreeNode::Array(v) => {
                 for (l, k) in v {
                     let mut new_offset = offset.to_vec();
                     new_offset.push(PathElement::ArrayEntry(*l));

src/ds/mismatch.rs

@@ -1,17 +1,17 @@
-use crate::ds::key_node::TreeNode;
+use crate::ds::key_node::DiffTreeNode;
 use crate::enums::{DiffEntry, DiffType};
 
 /// Structure holding the differences after a compare operation.
 /// For more readable access use the [`Mismatch::all_diffs`] method that yields a [`DiffEntry`] per diff.
 #[derive(Debug, PartialEq)]
 pub struct Mismatch {
-    pub left_only: TreeNode,
-    pub right_only: TreeNode,
-    pub unequal_values: TreeNode,
+    pub left_only: DiffTreeNode,
+    pub right_only: DiffTreeNode,
+    pub unequal_values: DiffTreeNode,
 }
 
 impl Mismatch {
-    pub fn new(l: TreeNode, r: TreeNode, u: TreeNode) -> Mismatch {
+    pub fn new(l: DiffTreeNode, r: DiffTreeNode, u: DiffTreeNode) -> Mismatch {
         Mismatch {
             left_only: l,
             right_only: r,
@@ -21,16 +21,16 @@ impl Mismatch {
 
     pub fn empty() -> Self {
         Mismatch {
-            left_only: TreeNode::Null,
-            unequal_values: TreeNode::Null,
-            right_only: TreeNode::Null,
+            left_only: DiffTreeNode::Null,
+            unequal_values: DiffTreeNode::Null,
+            right_only: DiffTreeNode::Null,
         }
     }
 
     pub fn is_empty(&self) -> bool {
-        self.left_only == TreeNode::Null
-            && self.unequal_values == TreeNode::Null
-            && self.right_only == TreeNode::Null
+        self.left_only == DiffTreeNode::Null
+            && self.unequal_values == DiffTreeNode::Null
+            && self.right_only == DiffTreeNode::Null
     }
 
     pub fn all_diffs(&self) -> Vec<(DiffType, DiffEntry)> {

src/enums.rs

@@ -40,38 +40,38 @@ impl Display for DiffType {
 }
 
 #[derive(Clone, Debug, PartialEq, Eq)]
-pub enum PathElement {
-    Object(String),
+pub enum PathElement<'a> {
+    Object(&'a str),
     ArrayEntry(usize),
 }
 
-impl PathElement {
-    pub fn resolve<'a>(&self, v: &'a serde_json::Value) -> Option<&'a serde_json::Value> {
+impl<'a> PathElement<'a> {
+    pub fn resolve<'b>(&self, v: &'b serde_json::Value) -> Option<&'b serde_json::Value> {
         match self {
             PathElement::Object(o) => v.get(o),
             PathElement::ArrayEntry(i) => v.get(*i),
         }
     }
 
-    pub fn resolve_mut<'a>(
+    pub fn resolve_mut<'b>(
         &self,
-        v: &'a mut serde_json::Value,
-    ) -> Option<&'a mut serde_json::Value> {
+        v: &'b mut serde_json::Value,
+    ) -> Option<&'b mut serde_json::Value> {
         match self {
             PathElement::Object(o) => v.get_mut(o),
             PathElement::ArrayEntry(i) => v.get_mut(*i),
         }
     }
 }
 
-/// Represents a single difference in a JSON file
+/// A view on a single end-node of the [`DiffKeyNode`] tree.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
-pub struct DiffEntry {
-    pub path: Vec<PathElement>,
-    pub values: Option<(String, String)>,
+pub struct DiffEntry<'a> {
+    pub path: Vec<PathElement<'a>>,
+    pub values: Option<(&'a serde_json::Value, &'a serde_json::Value)>,
 }
 
-impl Display for DiffEntry {
+impl Display for DiffEntry<'_> {
     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
         for element in &self.path {
             write!(f, ".{element}")?;
@@ -87,7 +87,7 @@ impl Display for DiffEntry {
     }
 }
 
-impl Display for PathElement {
+impl Display for PathElement<'_> {
     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
         match self {
             PathElement::Object(o) => {

src/lib.rs

@@ -1,8 +1,7 @@
 //! # Library for comparing JSON data structures
 //! ## Summary
 //! Main entry points are [`compare_strs`] to compare string slices and [`compare_serde_values`] to compare already parse [`serde_json::Value`]
-//! ## Examples:
-//! ### Compare string slices:
+//! ## Example:
 //! ```rust
 //! use json_diff::compare_strs;
 //! let data1 = r#"["a",{"c": ["d","f"] },"b"]"#;
@@ -17,14 +16,21 @@
 //!   r#".[0].c.[1].("f" != "e")"#
 //! );
 //! ```
+//! ## How to handle the results
+//! Results are returned in a triple of [`DiffTreeNode`] called [`Mismatch`].
+//! The triple consists of values only on the left side, values only on the right side and values on both sides that differ.
+//! Since tree traversal is not usually what you want to do on client side, [`DiffTreeNode`] offers [`DiffTreeNode::get_diffs`] to retrieve
+//! a flat list of [`DiffEntry`] which is more easily usable. The path in the json is collapsed into a vector of [`PathElement`] which can be used to follow the diff.
+//! Similarly, all diffs after an operation can be collected using [`Mismatch::all_diffs`].
 //!
 //!
 
 pub mod ds;
 
 pub mod enums;
 pub mod process;
-pub use ds::key_node::TreeNode;
+pub use ds::key_node::DiffTreeNode;
+pub use ds::mismatch::Mismatch;
 pub use enums::DiffEntry;
 pub use enums::DiffType;
 pub use enums::Error;