rclap

rclap is a Rust utility that helps you create command-line interfaces with the clap crate by reducing boilerplate code. It generates clap structures from a simple TOML configuration file, allowing you to define your application's command-line arguments, environment variables, and default values in one place.

How it works

1- Create a TOML File: Define your configuration settings in a simple TOML file, specifying the argument name, type, default value, and associated environment variable.

port = { type = "u16", default = "8080", doc = "Server port number", env = "PORT" }
ip = {  default = "localhost", doc = "connection URL", env = "URL" }

2- Apply the Macro: Use the #[config] macro on an empty struct in your Rust code. The macro reads the TOML file and generates the complete clap::Parser implementation for you.

use clap::Parser;
use rclap::config;

#[config]
struct MyConfig;

3- Parse and Use: Your application can then simply call MyConfig::parse() to handle all command-line and environment variable parsing.

fn main() {
    let config = MyConfig::parse();
    println!("Config: {:#?}", config);
    println!("{}", &config.port);
}

rclap prioritizes a hierarchical approach to configuration, allowing you to set the ip and port via either environment variables or command-line arguments. If neither is specified, the predefined default values will be used.

For instance, you can use the command-line flags --ip and --port to pass values directly. This would generate a help message like the one below, which clearly shows the available options, their default values, and the corresponding environment variables.

Usage: example [OPTIONS]

Options:
      --"ip" <ip>      connection URL [env: URL=] [default: localhost]
      --"port" <port>  Server port number [env: PORT=120] [default: 8080]
  -h, --help           Print help

The equivalent for the above code will be generated by the macro:

   #[derive(Debug, Clone, PartialEq, Default, Parser)]
   pub struct MyConfig {
        ///Server port number
        #[arg(
            id = "port",
            default_value_t = 8080,
            env = "PORT",
            long = stringify!("port")
        )]
        pub port: u16,
        ///connection URL
        #[arg(
            id = "ip",
            default_value = "localhost",
            env = "URL",
            long = stringify!("ip")
        )]
        pub ip: String,
    }

The example folder contains more working samples.

Settings

dependencies

The rclap utility is a macro generator that relies on two core dependencies:

• clap: A powerful command-line argument parser for Rust. rclap uses it to parse command-line arguments and generate help messages.

• toml: A library for parsing and handling TOML files. rclap uses it to read the configuration settings you define in your .toml file.

To use rclap, you must add clap to your Cargo.toml file with the env and derive features enabled, as shown in the example below.

clap = { version = "4.5", features = ["env", "derive"] }