ClapCmd

A library to quickly build full-featured REPLs supported by CLAP and readline (provided via rustyline)

Features

• Full readline support that exposes all customization for rustyline
  • emacs-style keyboard shortcuts
  • command history
• Full integration with clap builders allowing for full-featured commands
• Tab completion for:
  • commands and (TODO) command aliases
  • arguments
  • subcommands
  • values supplied via value_parsers (i.e. a list of valid values)
  • value hints (e.g. ValueHint::FilePath)
  • TODO: callback and/or demo for how to query value_parsers at runtime
• Callback style approach with provided state
• Customizable prompts that can be updated at anytime during execution
• Support for writing to stdout outside of the command loop without mangling the input line via get_async_writer()
• Create loadable and unloadable command groups
• Automated testing via the test-runner feature

Basic Example

A minimal example showing a basic REPL is as follows:

```rust use clapcmd::{ArgMatches, ClapCmd, ClapCmdResult, Command};

fn do_ping(cmd: &mut ClapCmd, _: ArgMatches) -> ClapCmdResult { cmd.output("pong"); Ok(()) }

fn main() { let mut cmd = ClapCmd::default(); cmd.addcommand( doping, Command::new("ping").about("do a ping") ); cmd.run_loop(); } ```

With State

To pass state or persistent information to callbacks, provide a State class like so. The State class must implement Clone and Default traits, and can be accessed via the get_state() and set_state() methods on the ClapCmd reference passed into the callback.

```rust use clapcmd::{ArgMatches, ClapCmd, ClapCmdResult, Command};

[derive(Clone, Default)]

struct State { counter: u32, }

fn docount(cmd: &mut ClapCmd, _: ArgMatches) -> ClapCmdResult where State: Clone + Default, { let state = cmd.getstate(); let newcount = state.counter + 1; cmd.output(format!("{newcount}")); cmd.setstate(State { counter: newcount }); Ok(()) }

fn main() { let mut cmd = ClapCmd::::default(); cmd.addcommand( docount, Command::new("count").about("increment a counter") ); cmd.run_loop(); } ```

E2E Testing

By enabling the test-runner feature and using the built-in output, success, info, warn, and error functions, it is easy to automate e2e tests of your CLI. See the tests/ folder for more examples.

```rust use clapcmd::{ArgMatches, ClapCmd, ClapCmdResult, Command};

fn do_hello(cmd: &mut ClapCmd, _: ArgMatches) -> ClapCmdResult { cmd.output("hello"); Ok(()) }

let mut cmd = ClapCmd::default(); cmd.addcommand( dohello, Command::new("hello").about("simple hello world") ); let _ = cmd.onecmd("goodbye"); assert!( cmd.error.contains("unknown command"), "did not detect invalid command", ); let _ = cmd.onecmd("hello"); assert!( cmd.output.contains("hello"), "did not run hello world command correctly", ); ```

Other Examples

Refer to the examples/ folder for more demonstrations of advanced use cases

MSRV

This library is tested with Rust 1.65 along with the latest version of Rust

Related Projects

• reedline-repl-rs https://github.com/arturh85/reedline-repl-rs