clap_reverse 0.1.1

Derive macro for building `std::process:Command` from a Rust struct
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

# clap_reverse [![Pipeline Status](https://img.shields.io/gitlab/pipeline-status/h45h%2Fclap_reverse?branch=master)](https://gitlab.com/h45h/clap_reverse/-/pipelines) [![Crates Version](https://img.shields.io/crates/v/clap_reverse.svg)](https://crates.io/crates/clap_reverse) [![Documentation](https://docs.rs/clap_reverse/badge.svg)](https://docs.rs/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](./examples) directory and runned via `cargo r --example <example_name>`.

## Usage

```rust
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.

1. Only boolean fields may use the `flag` attribute. Flags appear in the command only if `true`.
2. 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.
3. Fields of type `Option<T>` are appended only if `Some(value)`; otherwise they are skipped.
4. 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.
5. Prefixes and delimiters can be overridden on a per-field basis; field-level attributes take precedence over struct-level defaults.
6. If the `name` attribute is not provided, the Rust field name is used as the argument name.


## License

[MIT](./LICENSE) license: feel free to steal, sell, use as a drug, modify, etc.