Add example for outside type registration

1 files changed, 91 insertions, 0 deletions

diff --git a/mingling/src/example_docs.rs b/mingling/src/example_docs.rs
index b1d693b..5ea04b1 100644
--- a/mingling/src/example_docs.rs
+++ b/mingling/src/example_docs.rs
@@ -1550,6 +1550,97 @@ pub mod example_implicit_dispatcher {}
 /// gen_program!();
 /// ```
 pub mod example_lazy_resources {}
+/// Example: Using the `group!()` Macro to Register Outside Types
+///
+///  This example demonstrates how to use the `group!()` macro to make outside
+///  types (from `std` or other crates) recognizable by the Mingling framework,
+///  without modifying the original type definition.
+///
+///  Run:
+///  ```bash
+///  cargo run --manifest-path examples/example-outside-type/Cargo.toml --quiet -- parse 42
+///  cargo run --manifest-path examples/example-outside-type/Cargo.toml --quiet -- parse hello
+///  ```
+///
+///  Output:
+///  ```plaintext
+///  Parsed number: 42
+///  Parse error: invalid digit found in string
+///  ```
+///
+/// Source code (./Cargo.toml)
+/// ```toml
+/// [package]
+/// name = "example-outside-type"
+/// version = "0.1.0"
+/// edition = "2024"
+///
+/// [dependencies.mingling]
+/// path = "../../mingling"
+/// features = [
+///     "extra_macros",
+/// ]
+///
+/// [workspace]
+/// ```
+///
+/// Source code (./src/main.rs)
+/// ```ignore
+/// use mingling::{macros::group, prelude::*};
+/// use std::num::ParseIntError;
+///
+/// dispatcher!("parse");
+///
+/// // --------- IMPORTANT ---------
+/// // You can directly use the `group!` macro to define outside types as types
+/// // recognizable by Mingling
+/// //      _____________ from std::num::ParseIntError
+/// //     /
+/// //     vvvvvvvvvvvvv
+/// group!(ParseIntError);
+/// // --------- IMPORTANT ---------
+///
+/// pack!(ParsedNumber = i32);
+///
+/// /// Parse the first argument as an `i32`
+/// ///
+/// /// On success, routes to `render_number`.
+/// /// On failure, routes to `render_parse_error` via the registered outside type.
+/// #[chain]
+/// fn parse_number(args: EntryParse) -> Next {
+///     let input = args.inner.first().cloned().unwrap_or_default();
+///     match input.parse::<i32>() {
+///         Ok(num) => ParsedNumber::new(num).to_chain(),
+///         Err(e) => e.to_chain(),
+///     }
+/// }
+///
+/// /// Renderer for successful parse — displays the parsed integer.
+/// //                     _____________ Using std::num::ParseIntError as a chain input
+/// //                    /
+/// #[renderer] //        vvvvvvvvvvvv
+/// fn render_number(num: ParsedNumber) {
+///     r_println!("Parsed number: {}", *num);
+/// }
+///
+/// /// Renderer for parse errors — using the outside `ParseIntError` type.
+/// ///
+/// /// The `ParseIntError` type is registered via `group!` above, so it implements
+/// /// `Groupped<ThisProgram>` and can be used directly in a `#[renderer]` function.
+/// #[renderer]
+/// fn render_parse_error(err: ParseIntError) {
+///     r_println!("Parse error: {}", err);
+/// }
+///
+/// fn main() {
+///     let mut program = ThisProgram::new();
+///     program.with_dispatcher(CMDParse);
+///     program.exec_and_exit();
+/// }
+///
+/// gen_program!();
+/// ```
+pub mod example_outside_type {}
 /// Example `pack_err!`
 ///
 ///  > This example demonstrates how to use the `pack_err!` macro to define error types