Add example for clap binding integration

1 files changed, 128 insertions, 0 deletions

diff --git a/mingling/src/example_docs.rs b/mingling/src/example_docs.rs
index 81ba3fc..b5a78ea 100644
--- a/mingling/src/example_docs.rs
+++ b/mingling/src/example_docs.rs
@@ -289,6 +289,134 @@ pub mod example_async_support {}
 /// gen_program!();
 /// ```
 pub mod example_basic {}
+/// 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'.
+///  ```
+///
+/// Source code (./Cargo.toml)
+/// ```toml
+/// [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"]
+/// ```
+///
+/// Source code (./src/main.rs)
+/// ```ignore
+/// 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!();
+/// ```
+pub mod example_clap_binding {}
 /// Example Completion
 ///
 ///  > This example demonstrates how to use **Mingling** to create fully dynamic command-line completions