refactor(serde_yml): ♻️ add unit tests and examples for path.rs

examples/example.rs

@@ -11,6 +11,9 @@
 /// Contains the example modules for the `loader` module.
 mod loader;
 
+/// Contains the example modules for the `modules` module.
+mod modules;
+
 /// Contains the example modules for the `serializer` module.
 mod serializer;
 
@@ -29,6 +32,9 @@ fn main() {
     // Run the example module `loader`.
     loader::main();
 
+    // Run the example module `modules`.
+    modules::main();
+
     // Run the example module `serializer`.
     serializer::main();
 

examples/modules/mod.rs

@@ -0,0 +1,8 @@
+/// This module contains the `path` example.
+pub(crate) mod path_examples;
+
+/// The main function that runs all the example modules.
+pub(crate) fn main() {
+    // Run the example module `path`.
+    path_examples::main();
+}

examples/modules/path_examples.rs

@@ -0,0 +1,230 @@
+//! Examples for the `Path` enum and its usage in the `path` module.
+//!
+//! This file demonstrates the creation, usage, and formatting of `Path` instances,
+//! as well as handling various path scenarios.
+
+use serde_json::to_string;
+use serde_yml::modules::path::Path;
+
+pub(crate) fn main() {
+    // Print a message to indicate the file being executed.
+    println!("\n❯ Executing examples/libyml/path_examples.rs");
+
+    // Example: Creating a Path::Root instance
+    let path_root = Path::Root;
+    println!("\n✅ Created a Path::Root instance: {}", path_root); // Output: .
+
+    // Example: Creating a Path::Seq instance
+    let path_seq = Path::Seq {
+        parent: &path_root,
+        index: 42,
+    };
+    println!("\n✅ Created a Path::Seq instance: {}", path_seq); // Output: [42]
+
+    // Example: Creating a Path::Map instance
+    let path_map = Path::Map {
+        parent: &path_root,
+        key: "key",
+    };
+    println!("\n✅ Created a Path::Map instance: {}", path_map); // Output: key
+
+    // Example: Creating a Path::Alias instance
+    let path_alias = Path::Alias { parent: &path_root };
+    println!("\n✅ Created a Path::Alias instance: {}", path_alias); // Output: (empty string)
+
+    // Example: Creating a Path::Unknown instance
+    let path_unknown = Path::Unknown { parent: &path_root };
+    println!("\n✅ Created a Path::Unknown instance: {}", path_unknown); // Output: ?
+
+    // Example: Nested paths
+    let path_nested = Path::Unknown {
+        parent: &Path::Alias {
+            parent: &Path::Map {
+                parent: &Path::Seq {
+                    parent: &path_root,
+                    index: 0,
+                },
+                key: "key",
+            },
+        },
+    };
+    println!("\n✅ Created a nested Path instance: {}", path_nested); // Output: [0].key..?
+
+    // Example: Deeply nested paths
+    let path_deeply_nested = Path::Unknown {
+        parent: &Path::Alias {
+            parent: &Path::Map {
+                parent: &Path::Seq {
+                    parent: &Path::Map {
+                        parent: &Path::Seq {
+                            parent: &path_root,
+                            index: 1,
+                        },
+                        key: "first",
+                    },
+                    index: 2,
+                },
+                key: "second",
+            },
+        },
+    };
+    println!(
+        "\n✅ Created a deeply nested Path instance: {}",
+        path_deeply_nested
+    ); // Output: [1].first[2].second..?
+
+    // Example: Path with an empty key in Path::Map
+    let path_map_empty_key = Path::Map {
+        parent: &path_root,
+        key: "",
+    };
+    println!(
+        "\n✅ Created a Path::Map instance with an empty key: {}",
+        path_map_empty_key
+    ); // Output: (empty string)
+
+    // Example: Path with maximum index in Path::Seq
+    let path_seq_max_index = Path::Seq {
+        parent: &path_root,
+        index: usize::MAX,
+    };
+    println!(
+        "\n✅ Created a Path::Seq instance with max index: {}",
+        path_seq_max_index
+    ); // Output: [18446744073709551615]
+
+    // Example: Complex nested paths
+    let path_complex_nested = Path::Unknown {
+        parent: &Path::Alias {
+            parent: &Path::Map {
+                parent: &Path::Seq {
+                    parent: &Path::Map {
+                        parent: &Path::Seq {
+                            parent: &Path::Map {
+                                parent: &path_root,
+                                key: "third",
+                            },
+                            index: 3,
+                        },
+                        key: "second",
+                    },
+                    index: 2,
+                },
+                key: "first",
+            },
+        },
+    };
+    println!(
+        "\n✅ Created a complex nested Path instance: {}",
+        path_complex_nested
+    ); // Output: [2].first[3].second.third..?
+
+    // Example: Path with multiple unknowns
+    let path_multiple_unknowns = Path::Unknown {
+        parent: &Path::Unknown {
+            parent: &Path::Unknown { parent: &path_root },
+        },
+    };
+    println!(
+        "\n✅ Created a Path instance with multiple unknowns: {}",
+        path_multiple_unknowns
+    ); // Output: .?.?.?
+
+    // Example: Path with multiple aliases
+    let path_multiple_aliases = Path::Alias {
+        parent: &Path::Alias {
+            parent: &Path::Alias { parent: &path_root },
+        },
+    };
+    println!(
+        "\n✅ Created a Path instance with multiple aliases: {}",
+        path_multiple_aliases
+    ); // Output: ..
+
+    // Example: Path with multiple sequences
+    let path_multiple_sequences = Path::Seq {
+        parent: &Path::Seq {
+            parent: &Path::Seq {
+                parent: &path_root,
+                index: 1,
+            },
+            index: 2,
+        },
+        index: 3,
+    };
+    println!(
+        "\n✅ Created a Path instance with multiple sequences: {}",
+        path_multiple_sequences
+    ); // Output: \[1\].\[2\].\[3\]
+
+    // Example: Path with multiple maps
+    let path_multiple_maps = Path::Map {
+        parent: &Path::Map {
+            parent: &Path::Map {
+                parent: &path_root,
+                key: "first",
+            },
+            key: "second",
+        },
+        key: "third",
+    };
+    println!(
+        "\n✅ Created a Path instance with multiple maps: {}",
+        path_multiple_maps
+    ); // Output: first.second.third
+
+    // Example: Path with multiple aliases, sequences, and maps
+    let path_multiple_nested = Path::Alias {
+        parent: &Path::Seq {
+            parent: &Path::Map {
+                parent: &Path::Alias { parent: &path_root },
+                key: "first",
+            },
+            index: 2,
+        },
+    };
+    println!(
+        "\n✅ Created a Path instance with multiple nested paths: {}",
+        path_multiple_nested
+    ); // Output: .first.\[2\].
+
+    // Example: Path with multiple unknowns, aliases, sequences, and maps
+    let path_multiple_complex = Path::Unknown {
+        parent: &Path::Alias {
+            parent: &Path::Seq {
+                parent: &Path::Map {
+                    parent: &Path::Unknown { parent: &path_root },
+                    key: "first",
+                },
+                index: 2,
+            },
+        },
+    };
+    println!(
+        "\n✅ Created a Path instance with multiple complex paths: {}",
+        path_multiple_complex
+    ); // Output: ?.first.\[2\]..?
+
+    // Example: Serializing and deserializing Path instances
+    let path_to_serialize = Path::Seq {
+        parent: &path_root,
+        index: 42,
+    };
+
+    let serialized = to_string(&path_to_serialize).unwrap();
+    println!("\n✅ Serialized Path::Seq instance: {}", serialized);
+
+    // Example: Comparing Path instances
+    let another_path_seq = Path::Seq {
+        parent: &path_root,
+        index: 42,
+    };
+    if path_seq == another_path_seq {
+        println!("\n✅ The path_seq is equal to another_path_seq.");
+    } else {
+        println!("\n❌ The path_seq is not equal to another_path_seq.");
+    }
+
+    // Example: Debug representation of Path instances
+    println!("\n✅ Debug representation of path_seq: {:?}", path_seq);
+}

src/modules/path.rs

@@ -1,3 +1,4 @@
+use serde::Serialize;
 use std::fmt::{self, Display};
 
 /// `Path` represents the path to the current value in the input, like `dependencies.serde.typo1`.
@@ -12,7 +13,7 @@ use std::fmt::{self, Display};
 /// - `Map`: Represents a map (object) path with a reference to the parent path and a key.
 /// - `Alias`: Represents an alias path with a reference to the parent path.
 /// - `Unknown`: Represents an unknown path with a reference to the parent path.
-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, PartialEq, Serialize)]
 pub enum Path<'a> {
     /// Represents the root path.
     Root,

tests/mod.rs

@@ -4,6 +4,9 @@ pub mod libyml;
 /// This module contains the tests for the `macros` module.
 pub mod macros;
 
+/// This module contains the tests for the `modules` module.
+pub mod modules;
+
 /// This module contains the tests for the `utilities` module.
 pub mod utilities;
 

tests/modules/mod.rs

@@ -0,0 +1,2 @@
+/// This module contains the tests for the `path` module.
+pub mod test_path;