Make JSON more useful

src/app.rs

@@ -4,7 +4,7 @@ pub use sub::Sub;
 
 use crate::{
     args::{Args, Quantity},
-    json_data::JsonData,
+    json_data::{JsonData, UnitAndTree},
     reporter::{ErrorOnlyReporter, ErrorReport, ProgressAndErrorReporter, ProgressReport},
     runtime_error::RuntimeError,
     size::{Bytes, Size},
@@ -59,9 +59,10 @@ impl App {
             } = self.args;
             let direction = Direction::from_top_down(top_down);
 
-            let json_data = stdin()
+            let unit_and_tree = stdin()
                 .pipe(serde_json::from_reader::<_, JsonData>)
-                .map_err(RuntimeError::DeserializationFailure)?;
+                .map_err(RuntimeError::DeserializationFailure)?
+                .unit_and_tree;
 
             macro_rules! visualize {
                 ($reflection:expr, $bytes_format: expr) => {{
@@ -79,9 +80,9 @@ impl App {
                 }};
             }
 
-            let visualization = match json_data {
-                JsonData::Bytes(reflection) => visualize!(reflection, bytes_format),
-                JsonData::Blocks(reflection) => visualize!(reflection, ()),
+            let visualization = match unit_and_tree {
+                UnitAndTree::Bytes(reflection) => visualize!(reflection, bytes_format),
+                UnitAndTree::Blocks(reflection) => visualize!(reflection, ()),
             };
 
             print!("{}", visualization); // it already ends with "\n", println! isn't needed here.

src/app/sub.rs

@@ -2,7 +2,7 @@ use crate::{
     args::Fraction,
     data_tree::{DataTree, DataTreeReflection},
     fs_tree_builder::FsTreeBuilder,
-    json_data::JsonData,
+    json_data::{BinaryVersion, JsonData, SchemaVersion, UnitAndTree},
     os_string_display::OsStringDisplay,
     reporter::ParallelReporter,
     runtime_error::RuntimeError,
@@ -19,7 +19,7 @@ where
     Data: Size + Into<u64> + Serialize + Send + Sync,
     Report: ParallelReporter<Data> + Sync,
     GetData: Fn(&Metadata) -> Data + Copy + Sync,
-    DataTreeReflection<String, Data>: Into<JsonData>,
+    DataTreeReflection<String, Data>: Into<UnitAndTree>,
 {
     /// List of files and/or directories.
     pub files: Vec<PathBuf>,
@@ -48,7 +48,7 @@ where
     Data: Size + Into<u64> + Serialize + Send + Sync,
     Report: ParallelReporter<Data> + Sync,
     GetData: Fn(&Metadata) -> Data + Copy + Sync,
-    DataTreeReflection<String, Data>: Into<JsonData>,
+    DataTreeReflection<String, Data>: Into<UnitAndTree>,
 {
     /// Run the sub program.
     pub fn run(self) -> Result<(), RuntimeError> {
@@ -116,11 +116,16 @@ where
         };
 
         if json_output {
-            let json_data: JsonData = data_tree
+            let unit_and_tree: UnitAndTree = data_tree
                 .into_reflection() // I really want to use std::mem::transmute here but can't.
                 .par_convert_names_to_utf8() // TODO: allow non-UTF8 somehow.
                 .expect("convert all names from raw string to UTF-8")
                 .into();
+            let json_data = JsonData {
+                schema_version: SchemaVersion,
+                binary_version: Some(BinaryVersion::current()),
+                unit_and_tree,
+            };
             return serde_json::to_writer(stdout(), &json_data)
                 .map_err(RuntimeError::SerializationFailure);
         }

src/data_tree/reflection.rs

@@ -27,6 +27,7 @@ use serde::{Deserialize, Serialize};
 /// **Serialization and deserialization:** Requires enabling the `json` feature to enable `serde`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
+#[cfg_attr(feature = "json", serde(rename_all = "kebab-case"))]
 pub struct Reflection<Name, Data: Size> {
     /// Name of the tree.
     pub name: Name,

src/fs_tree_builder.rs

@@ -4,7 +4,6 @@ use super::{
     reporter::{error_report::Operation::*, ErrorReport, Event, Reporter},
     size::Size,
     tree_builder::{Info, TreeBuilder},
-    utils::path_name,
 };
 use pipe_trait::Pipe;
 use std::{
@@ -43,7 +42,7 @@ where
         } = builder;
 
         TreeBuilder::<PathBuf, OsStringDisplay, Data, _, _> {
-            name: path_name(&root),
+            name: OsStringDisplay::os_string_from(&root),
 
             path: root,
 

src/json_data.rs

@@ -1,3 +1,9 @@
+pub mod binary_version;
+pub mod schema_version;
+
+pub use binary_version::BinaryVersion;
+pub use schema_version::SchemaVersion;
+
 use crate::{
     data_tree::Reflection,
     size::{Blocks, Bytes},
@@ -7,14 +13,30 @@ use derive_more::{From, TryInto};
 #[cfg(feature = "json")]
 use serde::{Deserialize, Serialize};
 
-/// Output of the program with `--json-output` flag as well as
-/// input of the program with `--json-input` flag.
+/// The `"unit"` field and the `"tree"` field of [`JsonData`].
 #[derive(Debug, Clone, From, TryInto)]
 #[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
 #[cfg_attr(feature = "json", serde(tag = "unit", content = "tree"))]
-pub enum JsonData {
+#[cfg_attr(feature = "json", serde(rename_all = "kebab-case"))]
+pub enum UnitAndTree {
     /// Tree where data is [bytes](Bytes).
     Bytes(Reflection<String, Bytes>),
     /// Tree where data is [blocks](Blocks).
     Blocks(Reflection<String, Blocks>),
 }
+
+/// Output of the program with `--json-output` flag as well as
+/// input of the program with `--json-input` flag.
+#[derive(Debug, Clone)]
+#[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
+#[cfg_attr(feature = "json", serde(rename_all = "kebab-case"))]
+pub struct JsonData {
+    /// The `"schema-version"` field.
+    pub schema_version: SchemaVersion,
+    /// The `"pdu"` field.
+    #[cfg_attr(feature = "json", serde(rename = "pdu"))]
+    pub binary_version: Option<BinaryVersion>,
+    /// The `"unit"` field and the `"tree"` field.
+    #[cfg_attr(feature = "json", serde(flatten))]
+    pub unit_and_tree: UnitAndTree,
+}

src/json_data/binary_version.rs

@@ -0,0 +1,19 @@
+use derive_more::{AsMut, AsRef, From, FromStr, Into};
+
+#[cfg(feature = "json")]
+use serde::{Deserialize, Serialize};
+
+/// Version of the current `pdu` program.
+pub const CURRENT_VERSION: &str = env!("CARGO_PKG_VERSION");
+
+/// Version of the `pdu` program that created the input JSON.
+#[derive(Debug, Clone, PartialEq, Eq, AsMut, AsRef, From, FromStr, Into)]
+#[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
+pub struct BinaryVersion(String);
+
+impl BinaryVersion {
+    /// Get version of the current `pdu` program as a `BinaryVersion`.
+    pub fn current() -> Self {
+        CURRENT_VERSION.to_string().into()
+    }
+}

src/json_data/schema_version.rs

@@ -0,0 +1,46 @@
+#[cfg(feature = "json")]
+use derive_more::Display;
+#[cfg(feature = "json")]
+use serde::{Deserialize, Serialize};
+#[cfg(feature = "json")]
+use std::convert::TryFrom;
+
+/// Content of [`SchemaVersion`].
+pub const SCHEMA_VERSION: &str = "2021-06-05";
+
+/// Verifying schema version.
+#[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
+#[cfg_attr(feature = "json", serde(try_from = "String", into = "&str"))]
+pub struct SchemaVersion;
+
+/// Error when trying to parse [`SchemaVersion`].
+#[cfg(feature = "json")]
+#[derive(Debug, Display)]
+#[display(
+    fmt = "InvalidSchema: {:?}: input schema is not {:?}",
+    input,
+    SCHEMA_VERSION
+)]
+pub struct InvalidSchema {
+    /// The input string.
+    pub input: String,
+}
+
+#[cfg(feature = "json")]
+impl TryFrom<String> for SchemaVersion {
+    type Error = InvalidSchema;
+    fn try_from(input: String) -> Result<Self, Self::Error> {
+        if input == SCHEMA_VERSION {
+            Ok(SchemaVersion)
+        } else {
+            Err(InvalidSchema { input })
+        }
+    }
+}
+
+impl<'a> From<SchemaVersion> for &'a str {
+    fn from(_: SchemaVersion) -> Self {
+        SCHEMA_VERSION
+    }
+}

src/lib.rs

@@ -1,7 +1,5 @@
 #![deny(warnings)]
 
-mod utils;
-
 #[cfg(feature = "json")]
 pub use serde;
 #[cfg(feature = "json")]

tests/_utils.rs

@@ -144,10 +144,12 @@ where
         .into_reflection()
     };
 
+    let sub = |suffix: &str| root.join(suffix).pipe(OsStringDisplay::os_string_from);
+
     assert_eq!(
         measure("flat"),
         sanitize_tree_reflection(DataTreeReflection {
-            name: OsStringDisplay::os_string_from("flat"),
+            name: sub("flat"),
             data: suffix_size!("flat", "flat/0", "flat/1", "flat/2", "flat/3"),
             children: vec![
                 DataTreeReflection {
@@ -177,7 +179,7 @@ where
     assert_eq!(
         measure("nested"),
         sanitize_tree_reflection(DataTreeReflection {
-            name: OsStringDisplay::os_string_from("nested"),
+            name: sub("nested"),
             data: suffix_size!("nested", "nested/0", "nested/0/1"),
             children: vec![DataTreeReflection {
                 name: OsStringDisplay::os_string_from("0"),
@@ -194,7 +196,7 @@ where
     assert_eq!(
         measure("empty-dir"),
         sanitize_tree_reflection(DataTreeReflection {
-            name: OsStringDisplay::os_string_from("empty-dir"),
+            name: sub("empty-dir"),
             data: suffix_size!("empty-dir"),
             children: Vec::new(),
         }),