4 files changed, 326 insertions, 0 deletions
diff --git a/examples/example-command-macro/Cargo.lock b/examples/example-command-macro/Cargo.lock
new file mode 100644
index 0000000..025b322
--- /dev/null
+++ b/examples/example-command-macro/Cargo.lock
@@ -0,0 +1,234 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "arg-picker"
+version = "0.1.1"
+dependencies = [
+ "arg-picker-macros",
+ "just_fmt",
+]
+
+[[package]]
+name = "arg-picker-macros"
+version = "0.1.1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "example-command-macro"
+version = "0.1.0"
+dependencies = [
+ "mingling",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "just_fmt"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6170dccbc3ea15dfb7f2da964097f814aba1dd8f746d4ffc56f33245c38e6d96"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "might_be_async"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eca871cea620b07bd2e6da0c883891a25bead698c43a9ab64b0fd663a7a78d5f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+ "toml",
+]
+
+[[package]]
+name = "mingling"
+version = "0.3.0"
+dependencies = [
+ "arg-picker",
+ "mingling_core",
+ "mingling_macros",
+]
+
+[[package]]
+name = "mingling_core"
+version = "0.3.0"
+dependencies = [
+ "just_fmt",
+ "might_be_async",
+]
+
+[[package]]
+name = "mingling_macros"
+version = "0.3.0"
+dependencies = [
+ "just_fmt",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[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.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "serde_spanned"
+version = "0.6.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
+dependencies = [
+ "serde",
+]
+
+[[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 = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "toml"
+version = "0.8.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
+dependencies = [
+ "serde",
+ "serde_spanned",
+ "toml_datetime",
+ "toml_edit",
+]
+
+[[package]]
+name = "toml_datetime"
+version = "0.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.22.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
+dependencies = [
+ "indexmap",
+ "serde",
+ "serde_spanned",
+ "toml_datetime",
+ "toml_write",
+ "winnow",
+]
+
+[[package]]
+name = "toml_write"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "winnow"
+version = "0.7.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
+dependencies = [
+ "memchr",
+]
diff --git a/examples/example-command-macro/Cargo.toml b/examples/example-command-macro/Cargo.toml
new file mode 100644
index 0000000..b73c2c6
--- /dev/null
+++ b/examples/example-command-macro/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "example-command-macro"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies.mingling]
+path = "../../mingling"
+features = [
+    # Use `extra_macros` to introduce the `#[command]` macro
+    "extra_macros",
+
+    # Use `picker` to parse arguments
+    "picker",
+]
+
+[workspace]
diff --git a/examples/example-command-macro/page.toml b/examples/example-command-macro/page.toml
new file mode 100644
index 0000000..fe36d7a
--- /dev/null
+++ b/examples/example-command-macro/page.toml
@@ -0,0 +1,10 @@
+[example]
+id = "example-command-macro"
+name = "Command Macro"
+icon = "🚀"
+category = "advanced"
+desc = """
+Introduced how to use the `#[command]` macro to generate commands with minimal boilerplate
+"""
+tags = ["#[command]", "dispatcher!", "#[chain]"]
+files = ["src/main.rs", "Cargo.toml"]
diff --git a/examples/example-command-macro/src/main.rs b/examples/example-command-macro/src/main.rs
new file mode 100644
index 0000000..2bf932a
--- /dev/null
+++ b/examples/example-command-macro/src/main.rs
@@ -0,0 +1,66 @@
+//! Example Command Macro
+//!
+//! > Introduced how to use the `#[command]` macro to generate commands with minimal boilerplate
+//!
+//! Run:
+//! ```base
+//! cargo run --manifest-path examples/example-command-macro/Cargo.toml --quiet -- hello world
+//! cargo run --manifest-path examples/example-command-macro/Cargo.toml --quiet -- greet-someone Alice
+//! cargo run --manifest-path examples/example-command-macro/Cargo.toml --quiet -- goodbye
+//! ```
+//!
+//! Output:
+//! ```plaintext
+//! Hello, World
+//! Hello, Alice
+//! Goodbye!
+//! ```
+
+use mingling::{macros::buffer, picker::IntoPicker, prelude::*};
+
+fn main() {
+    let mut program = ThisProgram::new();
+
+    // Import the dispatchers generated by the `#[command]` macro
+    program.with_dispatcher(CMDHelloWorld);
+    program.with_dispatcher(CMDGreetSomeone);
+    program.with_dispatcher(CMDGoodBye);
+
+    program.exec_and_exit();
+}
+
+pack!(ResultGreeting = String);
+pack!(ResultGoodbye = ());
+
+// --------- IMPORTANT ---------
+// Auto-generates dispatcher!("hello.world", CMDHelloWorld => EntryHelloWorld);
+#[command]
+fn hello_world() -> ResultGreeting {
+    ResultGreeting::new("World".to_string())
+}
+
+// Auto-generates dispatcher!("hello-world", CMDGreetSomeone => EntryGreetSomeone);
+#[command(node = "greet-someone")]
+fn greet_someone(args: Vec<String>) -> ResultGreeting {
+    let name = args.pick_or(&arg![String], || "World".to_string()).unwrap();
+    ResultGreeting::new(name)
+}
+
+// Auto-generates dispatcher!("goodbye", CMDGoodBye => EntryGoodBye);
+#[command(name = CMDGoodBye, entry = EntryGoodBye)]
+fn goodbye() -> ResultGoodbye {
+    ResultGoodbye::default()
+}
+// --------- IMPORTANT ---------
+
+#[renderer(buffer)]
+fn render_greeting(result: ResultGreeting) {
+    r_println!("Hello, {}", *result);
+}
+
+#[renderer(buffer)]
+fn render_goodbye(_: ResultGoodbye) {
+    r_println!("Goodbye!");
+}
+
+gen_program!();