4 files changed, 245 insertions, 0 deletions
diff --git a/examples/example-structural-renderer/Cargo.lock b/examples/example-structural-renderer/Cargo.lock
new file mode 100644
index 0000000..cee5ae3
--- /dev/null
+++ b/examples/example-structural-renderer/Cargo.lock
@@ -0,0 +1,148 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "example-structural-renderer"
+version = "0.1.0"
+dependencies = [
+ "mingling",
+ "serde",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "just_fmt"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5454cda0d57db59778608d7a47bff5b16c6705598265869fb052b657f66cf05e"
+
+[[package]]
+name = "memchr"
+version = "2.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
+
+[[package]]
+name = "mingling"
+version = "0.2.0"
+dependencies = [
+ "mingling_core",
+ "mingling_macros",
+ "serde",
+ "size",
+]
+
+[[package]]
+name = "mingling_core"
+version = "0.2.0"
+dependencies = [
+ "just_fmt",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "mingling_macros"
+version = "0.2.0"
+dependencies = [
+ "just_fmt",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "size"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b6709c7b6754dca1311b3c73e79fcce40dd414c782c66d88e8823030093b02b"
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
diff --git a/examples/example-structural-renderer/Cargo.toml b/examples/example-structural-renderer/Cargo.toml
new file mode 100644
index 0000000..2090166
--- /dev/null
+++ b/examples/example-structural-renderer/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "example-structural-renderer"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+serde = { version = "1.0.228", features = ["derive"] }
+
+[dependencies.mingling]
+path = "../../mingling"
+features = [
+    "structural_renderer",
+    "parser",
+]
+
+[workspace]
diff --git a/examples/example-structural-renderer/page.toml b/examples/example-structural-renderer/page.toml
new file mode 100644
index 0000000..0ed7745
--- /dev/null
+++ b/examples/example-structural-renderer/page.toml
@@ -0,0 +1,10 @@
+[example]
+id = "example-structural-renderer"
+name = "structural renderer"
+icon = "📤"
+category = "output"
+desc = """
+Demonstrates how to render structured output in JSON or YAML using `StructuralRendererSetup` and the `structural_renderer` feature.
+"""
+tags = ["structural_renderer", "--json", "--yaml"]
+files = ["src/main.rs", "Cargo.toml"]
diff --git a/examples/example-structural-renderer/src/main.rs b/examples/example-structural-renderer/src/main.rs
new file mode 100644
index 0000000..21077e7
--- /dev/null
+++ b/examples/example-structural-renderer/src/main.rs
@@ -0,0 +1,71 @@
+//! Example structural renderer
+//!
+//! > This example demonstrates how to use the `structural_renderer` feature to render data into structures such as json / yaml
+//!
+//! Run
+//! ```bash
+//! cargo run --manifest-path examples/example-structural-renderer/Cargo.toml --quiet -- render Bob 22
+//! cargo run --manifest-path examples/example-structural-renderer/Cargo.toml --quiet -- render Bob 22 --json
+//! cargo run --manifest-path examples/example-structural-renderer/Cargo.toml --quiet -- render Bob 22 --yaml
+//! ```
+//!
+//! Output:
+//! ```plain
+//! Bob is 22 years old
+//! {"member_name":"Bob","member_age":22}
+//! member_name: Bob
+//! member_age: 22
+//! ```
+
+use mingling::prelude::*;
+use mingling::{parser::Picker, setup::StructuralRendererSetup, StructuralData, Groupped};
+use serde::Serialize;
+
+dispatcher!("render", CMDRender => EntryRender);
+
+fn main() {
+    let mut program = ThisProgram::new();
+    // Add `StructuralRendererSetup` to receive user input `--json` `--yaml` parameters
+    program.with_setup(StructuralRendererSetup);
+    program.with_dispatcher(CMDRender);
+    let _ = program.exec();
+}
+
+// --------- IMPORTANT ---------
+// For beautiful output structure, do not use `pack!` to wrap the types that need to be output.
+// Instead, manually implement
+//        __________________________________ Mark as structured data so it can be rendered
+//       /              ____________________ Implement serde::Serialize
+//       |             /           _________ Implement mingling::Groupped
+//       |             |          /            to ensure Mingling can recognize the type
+//       vvvvvvvvvvvv  vvvvvvvvv  vvvvvvvv
+#[derive(StructuralData, Serialize, Groupped)]
+struct Info {
+    #[serde(rename = "member_name")]
+    name: String,
+    #[serde(rename = "member_age")]
+    age: i32,
+}
+// This will output: {"member_name":"name","member_age":32} structure
+
+// If using pack!(Info = (String, i32));
+// Output: {"inner":["name", 32]}
+
+// --------- IMPORTANT ---------
+
+#[chain]
+fn parse_render(prev: EntryRender) -> Next {
+    let (name, age) = Picker::new(prev.inner)
+        .pick::<String>(())
+        .pick::<i32>(())
+        .unpack();
+    Info { name, age }.to_render()
+}
+
+/// Implement default renderer for when structural_renderer is not specified
+#[renderer]
+fn render_info(prev: Info) {
+    r_println!("{} is {} years old", prev.name, prev.age);
+}
+
+gen_program!();