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
- semicolon (
- Automated testing via the
test-runner
feature
Basic Example
A minimal example showing a basic REPL is as follows:
use ;
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.
use ;
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
use ;
use Lazy;
static LOADED_GROUP: = new;
static UNLOADED_GROUP: = new;
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.
use ;
let mut cmd = default;
cmd.add_command;
let _ = cmd.one_cmd;
assert!;
let _ = cmd.one_cmd;
assert!;
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