Add example for clap binding integration

3 files changed, 338 insertions, 0 deletions

diff --git a/examples/example-clap-binding/Cargo.lock b/examples/example-clap-binding/Cargo.lock
new file mode 100644
index 0000000..a2f2303
--- /dev/null
+++ b/examples/example-clap-binding/Cargo.lock
@@ -0,0 +1,218 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys",
+]
+
+[[package]]
+name = "clap"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
+[[package]]
+name = "example-clap-binding"
+version = "0.1.0"
+dependencies = [
+ "clap",
+ "mingling",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
+[[package]]
+name = "just_fmt"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5454cda0d57db59778608d7a47bff5b16c6705598265869fb052b657f66cf05e"
+
+[[package]]
+name = "mingling"
+version = "0.1.9"
+dependencies = [
+ "mingling_core",
+ "mingling_macros",
+]
+
+[[package]]
+name = "mingling_core"
+version = "0.1.9"
+dependencies = [
+ "just_fmt",
+]
+
+[[package]]
+name = "mingling_macros"
+version = "0.1.9"
+dependencies = [
+ "just_fmt",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
+[[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.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+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 = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
diff --git a/examples/example-clap-binding/Cargo.toml b/examples/example-clap-binding/Cargo.toml
new file mode 100644
index 0000000..d261786
--- /dev/null
+++ b/examples/example-clap-binding/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "example-clap-binding"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies.mingling]
+path = "../../mingling"
+# Enable `clap` features
+features = ["clap"]
+
+# Import `clap` to your project
+[dependencies.clap]
+version = "4.6.1"
+# Enable `derive` features
+features = ["derive"]
diff --git a/examples/example-clap-binding/src/main.rs b/examples/example-clap-binding/src/main.rs
new file mode 100644
index 0000000..fd813a6
--- /dev/null
+++ b/examples/example-clap-binding/src/main.rs
@@ -0,0 +1,105 @@
+//! Example Clap Binding
+//!
+//! > This example demonstrates how to bind clap_derive to Mingling
+//!
+//! **Note**:
+//! If the `error` parameter of the `dispatcher_clap!` macro is enabled, parameters will be parsed using `try_parse_from`
+//! This will cause clap's ColorChoice output to be plain text without ANSI colors
+//!
+//! Run:
+//! ```bash
+//! cargo run --manifest-path examples/example-clap-binding/Cargo.toml --quiet -- greet
+//! cargo run --manifest-path examples/example-clap-binding/Cargo.toml --quiet -- greet Alice
+//! cargo run --manifest-path examples/example-clap-binding/Cargo.toml --quiet -- greet Alice -r 5
+//! cargo run --manifest-path examples/example-clap-binding/Cargo.toml --quiet -- greet --help
+//! cargo run --manifest-path examples/example-clap-binding/Cargo.toml --quiet -- greet --rppat
+//! ```
+//!
+//! Output:
+//! ```plaintext
+//! Hello, World!
+//! Hello, Alice!
+//! Hello, Alice, Alice, Alice, Alice, Alice!
+//! Usage: example-clap-binding [OPTIONS] [NAME]
+//!
+//! Arguments:
+//!   [NAME]  [default: World]
+//!
+//! Options:
+//!   -r, --repeat <REPEAT>  [default: 1]
+//!   -h, --help             Print help
+//!
+//! error: unexpected argument '--rppat' found
+//!
+//!   tip: a similar argument exists: '--repeat'
+//!
+//! Usage: example-clap-binding --repeat <REPEAT> [NAME]
+//!
+//! For more information, try '--help'.
+//! ```
+
+use mingling::{macros::dispatcher_clap, prelude::*, Groupped};
+
+fn main() {
+    let mut program = ThisProgram::new();
+
+    // Set clap help output mode
+    program.stdout_setting.clap_help_print_behaviour =
+        mingling::ClapHelpPrintBehaviour::PrintDirectly;
+    //  mingling::ClapHelpPrintBehaviour::WriteToRenderResult
+    //
+    // PrintDirectly:
+    //   Let Clap print help information directly to stdout
+    //
+    // WriteToRenderResult:
+    //   Capture Clap's help information and write to RenderResult
+
+    program.with_dispatcher(CMDGreet);
+    program.exec_and_exit();
+}
+
+// Implement Clap Parser, and bind to Dispatcher
+//        _______________________________ Default trait, provides fallback on parse failure
+//       /         ______________________ clap::Parser, parsing logic implemented by Clap
+//       |        /              ________ Implement mingling::Groupped
+//       |        |             /           to ensure Mingling can recognize the type
+//       vvvvvvv  vvvvvvvvvvvv  vvvvvvvv
+#[derive(Default, clap::Parser, Groupped)]
+#[dispatcher_clap(
+    "greet", CMDGreet,       // Bind EntryGreet to "greet" command
+    help = true,             // Generate clap help for EntryGreet
+    error = ErrorGreetParsed // Generate and bind error type for parse failure
+//  ^^^^^\__ Using `error` intercepts parse failure information into the specified type,
+//              which is then rendered by the renderer
+)]
+pub struct EntryGreet {
+    // Positional argument
+    #[clap(default_value = "World")]
+    name: String,
+
+    // Option argument
+    #[arg(short, long, default_value_t = 1)]
+    repeat: i32,
+}
+
+#[renderer]
+fn render_greet(greet: EntryGreet) {
+    let name = greet.name;
+    let count = greet.repeat.max(0) as usize;
+
+    r_print!("Hello, ");
+    for i in 0..count {
+        r_print!("{name}");
+        if i < count - 1 {
+            r_print!(", ");
+        }
+    }
+    r_println!("!");
+}
+
+#[renderer]
+fn render_greet_parse_failed(err: ErrorGreetParsed) {
+    r_println!("{}", err.to_string());
+}
+
+gen_program!();