clap_reverse

[!NOTE] All documentation comments are written by a LLM (ChatGPT-5/3.0). This README.md was written by a LLM too.

Examples

all examples can be found in a examples directory and runned via cargo r --example <example_name>.

Usage

use clap_reverse::{AsCommand, ClapReverse};


// `#[derive(ClapReverse)]` generates `AsCommand` for the struct.
#[derive(Debug, ClapReverse)]
// `display` at the struct level implements `Display` to show the command line.
// `binary = "/my/binary/path"` at the struct level sets up a static path to the binary.
#[clap_reverse(display, binary = "echo")]
struct Echo {
    // Transparent fields are appended directly.
    #[clap_reverse(transparent)]
    text: String,
}

fn main() {
    let echo = Echo {
        text: "Hello, World!".to_string(),
    };

    println!("Echo structure: {echo:#?}");
    println!("Echo command: `{echo}`"); // echo Hello, World!
    println!("Echo execution result:"); // Hello, World!

    let exit_status = echo.as_command()
        .spawn()
        .expect("Failed to spawn `echo` command")
        .wait()
        .expect("Failed to wait on `echo` command");

    if !exit_status.success() {
        eprintln!("Something went wrong executing `echo` command");
    }
}

Struct Attributes

Struct-level attributes define defaults and global behaviors for the command:

Attribute	Description
`display`	Generates an implementation of [`std::fmt::Display`], which prints the equivalent command line string.
`prefix`	Sets a default prefix for all arguments (default `"--"`). Example: `prefix="-"` produces `-arg value`.
`delimiter`	Sets a delimiter between argument names and values (default `" "`). Example: `delimiter="="` produces `--arg=value`.
`binary`	Specifies a static binary for the command. Example: `binary="echo"` will always run the `echo` command.

Field Attributes

Field-level attributes customize the behavior of individual fields in the command:

Attribute	Description
`prefix`	Overrides the struct-level prefix for this field. Example: `prefix="-"` produces `-arg value`.
`name`	Overrides the field name in the command. If not set, the Rust field name is used.
`delimiter`	Overrides the struct-level delimiter for this field. Example: `delimiter="="` produces `--arg=value`.
`binary`	Marks a field as the binary source for the command. Only one field can have this.
`transparent`	Omits the argument name and prints only the value.
`flag`	Marks a boolean field as a flag that is included in the command only if `true`. Cannot be applied to non-boolean fields.

Note: All fields except those marked as flag must implement [std::fmt::Display].

Command Construction Rules

These rules govern how the macro generates a std::process::Command from a struct and its annotated fields.

Only boolean fields may use the flag attribute. Flags appear in the command only if true.
The binary attribute may appear either as a struct-level string or on a single field. Struct-level binary uses a fixed command name, while field-level binary derives the command from the field's value.
Fields of type Option<T> are appended only if Some(value); otherwise they are skipped.
Argument formatting generally follows {prefix}{name}{delimiter}{value}. Exceptions:
- transparent fields omit {prefix}{name}{delimiter} and print only the value.
- flag fields omit {delimiter}{value} entirely.
Prefixes and delimiters can be overridden on a per-field basis; field-level attributes take precedence over struct-level defaults.
If the name attribute is not provided, the Rust field name is used as the argument name.

License

MIT license: feel free to steal, sell, use as a drug, modify, etc.