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 by default (customizable via rustyline)
  • command history (in memory buffer)
• 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
• Multiline input support via the '\' character at end-of-line
• Combine multiple commands in one line via:
  • semicolon (;) for unconditional evaluation
  • double ampersand (&&) for chaining successful evaluations
  • double pipe (||) for error handling evaluations
• 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 trait, 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)]

struct State { counter: u32, }

fn docount(cmd: &mut ClapCmd, _: ArgMatches) -> ClapCmdResult { let state = cmd.getstate().okor("state missing")?; let newcount = state.counter + 1; cmd.info(format!("the count is now: {}", newcount)); cmd.setstate(State { counter: new_count }); Ok(()) }

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

Using Groups

Groups can be used to logically separate sets of commands in the built-in help menu. They can also be used to quickly activate and deactivate commands via the add_group and remove_group methods

```rust use clapcmd::{ArgMatches, ClapCmd, ClapCmdResult, Command, HandlerGroup}; use once_cell::sync::Lazy;

static LOADEDGROUP: Lazy = Lazy::new(|| { ClapCmd::group("Fruit") .description("Commands to do cool fruit things") .command( doapple, Command::new("apple").about("do the cool apple thing"), ) .command( dobanana, Command::new("banana").about("do the cool banana thing"), ) .command( dounload, Command::new("unload").about("unload the cool fruit group"), ) });

static UNLOADEDGROUP: Lazy = Lazy::new(|| { ClapCmd::unnamedgroup().command( do_load, Command::new("load").about("load the cool fruit group"), ) });

fn doload(cmd: &mut ClapCmd, _: ArgMatches) -> ClapCmdResult { cmd.addgroup(&LOADEDGROUP); cmd.removegroup(&UNLOADED_GROUP); cmd.info("loaded"); Ok(()) }

fn dounload(cmd: &mut ClapCmd, _: ArgMatches) -> ClapCmdResult { cmd.addgroup(&UNLOADEDGROUP); cmd.removegroup(&LOADED_GROUP); cmd.info("unloaded"); Ok(()) }

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

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

fn main() { let mut cmd = ClapCmd::default(); cmd.addgroup(&UNLOADEDGROUP); 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.one_cmd("goodbye");

[cfg(feature = "test-runner")]

assert!( cmd.error.contains("unknown command"), "did not detect invalid command", ); let _ = cmd.one_cmd("hello");

[cfg(feature = "test-runner")]

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