A lightweight framework that simplifies building complex command-line applications with clap.rs.
cling's name is a play on CLI-ng (as in next-gen) and "cling" the English word. It enables function handlers to cling to clap user-defined structs 😉.
While writing a command-line applications using the terrific clap crate, developers often write boilerplate functions that finds out which command the user has executed, collects the input types, then runs a handler function that does that job. This quickly gets repetitive for multi-command applications. Cling is designed to simplify that workflow and lets developers declaratively map commands to function.
#[cling(run = "my_function")]State<T>] value that can be extracted by downstream handlerssync or async functionsCredit: The handler design of cling is largely inspired by the excellent work done in [Axum](https://github.com/tokio-rs/axum).
For more details, see: - docs.rs - examples
Compiler support: requires rustc 1.70+
A quick-and-dirty example to show cling in action
```toml
[package] name = "cling-example" version = "0.1.0" edition = "2021"
[dependencies] clap = { version = "4.4.1", features = ["derive", "env"] } tokio = { version = "1.13.0", features = ["full"] } ```
Our main.rs might look something like this:
```rust, no_run
use cling::prelude::*;
// -- args --
/// A simple multi-command example using cling struct MyApp { #[clap(flatten)] pub opts: CommonOpts, #[clap(subcommand)] pub cmd: Command, }
struct CommonOpts { /// Turn debugging information on #[arg(short, long, global = true, action = clap::ArgAction::Count)] pub verbose: u8, }
// Commands for the app are defined here.
enum Command { /// Honk the horn! Honk(HonkOpts), #[cling(run = "beep")] /// Beep beep! Beep, }
// Options of "honk" command. We define cling(run=...) here to call the // function when this command is executed.
struct HonkOpts { /// How many times to honk? times: u8, }
// -- Handlers --
// We can access &CommonOpts because it derives [Collect] fn honk(commonopts: &CommonOpts, HonkOpts { times }: &HonkOpts) { if commonopts.verbose > 0 { println!("Honking {} times", times); }
(0..*times).for_each(|_| {
print!("Honk ");
});
println!("!");
}
// Maybe beeps need to be async! async fn beep() -> anyhow::Result<()> { println!("Beep, Beep!"); Ok(()) }
// -- main --
async fn main() -> ClingFinished
Now, let's run it and verify that it works as expected ```console $ simple-multi-command -v honk 5 Honking 5 times Honk Honk Honk Honk Honk !
```
Runnables refer to your clap structs that represent a CLI command. In cling,
any struct or enum that encodes the command tree must derive [Run], this
includes the top-level struct of your program (e.g. MyApp in the above demo).
The [Run] trait tells cling that this type should be attached to a handler
function. Essentially, structs that derive [Parser] or [Subcommand] will need to derive [Run].
For any struct/enum that derive [Run], a #[cling(run = ...)] attribute can be used to
associate a handler with it. It's possible to design a multi-level clap
program with handlers that run on each level, let's look at a few examples to understand
what's possible.
```rust, no_run use cling::prelude::*;
// standard clap attributes
pub struct MyApp { #[clap(short, long)] /// User name pub name: String, }
fn myonlyhandler(app: &MyApp) { println!("User is {}", app.name); }
async fn main() -> ClingFinished
``
Note: We derive [Collect] and [Clone] onMyAppin order to pass it down to
handlermyonlyhandleras shared referenceapp: &MyApp. Deriving [Collect]
is not necessary if your handler doesn't need access to&MyApp`.
Our program will now run the code in my_only_handler
txt
$ sample-1 --name=Steve
User is Steve
Given a command structure that looks like this:
txt
MyApp [CommonOpts]
- projects
|- create [CreateOpts]
|- list
- whoami
```rust,no_run
use cling::prelude::*;
pub struct MyApp { #[clap(flatten)] pub common: CommonOpts, #[command(subcommand)] pub cmd: Commands, }
pub struct CommonOpts {
/// Access token
#[arg(long, global = true)]
pub access_token: Option
pub enum Commands { /// Manage projects #[command(subcommand)] Projects(ProjectCommands), /// Self identification #[cling(run = "handlers::whoami")] WhoAmI, }
pub enum ProjectCommands { /// Create new project Create(CreateOpts), /// List all projects #[cling(run = "handlers::list_projects")] List, }
pub struct CreateOpts { /// Project name pub name: String, }
mod handlers { pub fn whoami() {} pub fn listprojects() {} pub fn createproject() {} }
``
-CommonOptsProgram-wide options. Any handler should be able to access it if it chooses to.
-ProjectOptsOptions forprojects [OPTIONS]
-CreateOptsOptions for theprojects createcommand
-ListOptsOptions for theprojects list` command
To understand how this works, consider the different set of options that can be passed in projects list subcommand:
txt
Usage: myapp [COMMON-OPTIONS] projects create <NAME>
Our runnables in this design are: MyApp, Commands, ProjectCommands, and CreateOpts.
We can attach a handler to any [Run] type by using #[cling(run = "...")] attribute.
This handler will run before any handler of sub-commands (if any). For enums that implement
[Subcommand], we must attach #[cling(run = "...")] on enum variants that do not
take any arguments (like ProjectCommands::List). However, for any enum variant that takes
arguments, the argument type itself must derive [Run].
Handlers are regular Rust functions that get executed when a clap command is run. Handlers latch
onto any type that derive [Run] using the #[cling(run = "function::path")] attribute.
Every type that has #[cling(run = ...)] will run its handler function before running the handlers
of the inner runnables.
Example ```rust,no_run use cling::prelude::*;
pub struct MyApp { #[clap(flatten)] pub common: CommonOpts, #[command(subcommand)] pub cmd: Commands, }
pub struct CommonOpts {
/// Access token
#[arg(long, global = true)]
pub access_token: Option
pub enum Commands { #[cling(run = "runbeep")] Beep, /// Self identification #[cling(run = "runwhoami")] WhoAmI, }
fn init() { println!("init handler!"); }
fn run_whoami() { println!("I'm groot!"); }
fn run_beep() { println!("Beep beep!"); }
async fn main() -> ClingFinished
init handler will always run before any other handlers in that structure.
```console $ many-handlers beep init handler! Beep beep!
```
| Feature | Activation | Effect
|----------|--------------------|--------
| derive | default | Enables #[derive(Run)] and #[derive(Collect)]
| shlex | "shlex" feature | Enables parsing from text, useful when building REPLs
Cling's minimum supported rust version is 1.70.0.
Dual-licensed under Apache 2.0 or MIT.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.