Docs(examples) create repl derive api example

Cargo.toml

@@ -159,6 +159,11 @@ name = "repl"
 path = "examples/repl.rs"
 required-features = ["help"]
 
+[[example]]
+name = "repl-derive"
+path = "examples/repl-derive.rs"
+required-features = ["derive"]
+
 [[example]]
 name = "01_quick"
 path = "examples/tutorial_builder/01_quick.rs"

examples/repl-derive.md

@@ -0,0 +1,41 @@
+**This requires enabling the [`derive` feature flag][crate::_features].**
+
+Help:
+```console
+$ echo --help
+Usage: echo --text <TEXT>
+
+Options:
+  -h, --help  Print help
+
+Echo:
+  -t, --text <TEXT>  The text to be echoed [aliases: text]
+$ ping --help
+Usage: ping
+
+Options:
+  -h, --help  Print help
+$ exit --help
+Usage: exit
+
+Options:
+  -h, --help  Print help
+```
+
+Echo:
+```console
+$ echo -t 'Hello, world!'
+Hello, world!
+```
+
+Ping:
+```console
+$ ping
+pong
+```
+
+Exit:
+```console
+$ exit
+Exiting ...
+```

examples/repl-derive.rs

@@ -0,0 +1,82 @@
+use std::io::Write;
+
+use clap::{Parser, Subcommand, Args};
+
+#[derive(Debug, Parser)]
+#[command(multicall = true)]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Debug, Subcommand)]
+enum Commands {
+    Echo(EchoArgs),
+    Ping,
+    Exit,
+}
+
+#[derive(Args, Debug)]
+pub struct EchoArgs {
+    #[arg(
+        short = 't', 
+        long = "text", 
+        visible_alias = "text",
+        help = "The text to be echoed",
+        help_heading = "Echo"
+    )]
+	text: String,
+}
+
+fn respond(line: &str) -> Result<bool, String> {
+    let args = shlex::split(line).ok_or("error: Invalid quoting")?;
+    let cli = Cli::try_parse_from(args).map_err(|e| e.to_string())?;
+    match cli.command {
+        Commands::Echo(args) => {
+            write!(std::io::stdout(), "{}\n", args.text).map_err(|e| e.to_string())?;
+            std::io::stdout().flush().map_err(|e| e.to_string())?;
+        }
+        Commands::Ping => {
+            write!(std::io::stdout(), "Pong\n").map_err(|e| e.to_string())?;
+            std::io::stdout().flush().map_err(|e| e.to_string())?;
+        }
+        Commands::Exit => {
+            write!(std::io::stdout(), "Exiting ...\n").map_err(|e| e.to_string())?;
+            std::io::stdout().flush().map_err(|e| e.to_string())?;
+            return Ok(true);
+        }
+    }
+    Ok(false)
+}
+
+fn readline() -> Result<String, String> {
+    write!(std::io::stdout(), "$ ").map_err(|e| e.to_string())?;
+    std::io::stdout().flush().map_err(|e| e.to_string())?;
+    let mut buffer = String::new();
+    std::io::stdin()
+        .read_line(&mut buffer)
+        .map_err(|e| e.to_string())?;
+    Ok(buffer)
+}
+
+fn main() -> Result<(), String> {
+    loop {
+        let line = readline()?;
+        let line = line.trim();
+        if line.is_empty() {
+            continue;
+        }
+        match respond(line) {
+            Ok(quit) => {
+                if quit {
+                    break;
+                }
+            }
+            Err(err) => {
+                write!(std::io::stdout(), "{err}").map_err(|e| e.to_string())?;
+                std::io::stdout().flush().map_err(|e| e.to_string())?;
+            }
+        }
+    }
+    Ok(())
+}

src/_cookbook/mod.rs

@@ -43,7 +43,7 @@
 //!   - Topics:
 //!     - Subcommands
 //!
-//! repl: [builder][repl]
+//! repl: [builder][repl], [derive][repl]
 //! - Topics:
 //!   - Read-Eval-Print Loops / Custom command lines
 
@@ -58,4 +58,5 @@ pub mod multicall_busybox;
 pub mod multicall_hostname;
 pub mod pacman;
 pub mod repl;
+pub mod repl_derive;
 pub mod typed_derive;

src/_cookbook/repl_derive.rs

@@ -0,0 +1,7 @@
+//! # Example: REPL (Derive API)
+//!
+//! ```rust
+#![doc = include_str!("../../examples/repl-derive.rs")]
+//! ```
+//!
+#![doc = include_str!("../../examples/repl-derive.md")]