yaml2cmd 0.1.2

A crate to build a `clap::Command` from yaml string at runtime.
Documentation
# `yaml2cmd`

[![Crates.io](https://img.shields.io/crates/v/yaml2cmd.svg)](https://crates.io/crates/yaml2cmd)
[![Docs.rs](https://docs.rs/yaml2cmd/badge.svg)](https://docs.rs/yaml2cmd)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A crate to build a `clap::Command` from YAML string at runtime. Define your entire CLI structure declaratively — no repetitive Rust boilerplate required.

## Features

- **Declarative Configuration** — Define your whole CLI in one YAML string.
- **Nested Subcommands** — Arbitrarily deep command hierarchies.
- **Rich Argument Options** — Short/long flags, required args, value ranges, actions, defaults, conflicts.
- **Hidden Commands** — Hide commands from help output.
- **Aliases** — Multiple aliases per command.
- **Automatic Sorting** — Commands and subcommands sorted alphabetically for consistent help output.
- **Debug-Only Commands** — Exclude commands from release builds via `debug_only` flag.
- **Runtime YAML** — Parse YAML from any source (file, string, network) at runtime.

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
yaml2cmd = "0.1"
clap = { version = "4", features = ["derive"] }
```

## Quick Start

### 1. Define your CLI in YAML

```yaml
# cli.yaml
commands:
  - name: create
    about: "Create a new resource"
    aliases: [new, make]
    args:
      - name: name
        short: n
        long: name
        help: "Name of the resource"
        required: true
        value_name: "NAME"
      - name: verbose
        short: v
        long: verbose
        help: "Enable verbose output"
        action: "set_true"
      - name: tags
        long: tags
        help: "Add tags to the resource"
        num_args: "1.."
        action: "append"
    subcommands:
      - name: file
        about: "Create a file resource"
        args:
          - name: path
            long: path
            help: "File path"
            required: true
      - name: directory
        about: "Create a directory resource"

  - name: delete
    about: "Delete a resource"
    hidden: true
    args:
      - name: force
        short: f
        long: force
        help: "Force deletion without confirmation"
        action: "set_true"

  - name: debug-info
    about: "Print debug information"
    debug_only: true
```

### 2. Build your CLI in Rust

```rust
use clap::Command;
use yaml2cmd::add_commands_from_yaml;

fn main() {
    // Load YAML from file, string, or any source
    let yaml_content = std::fs::read_to_string("cli.yaml")
        .expect("Failed to read cli.yaml");

    // Define the head command (root of your CLI)
    let head = Command::new("my-cli")
        .version("1.0.0")
        .about("My awesome CLI tool");

    // Build the full command tree
    let cmd = add_commands_from_yaml(&yaml_content, &head);

    // Parse and execute
    let matches = cmd.get_matches();
    // ... handle the matches
}
```

## YAML Schema Reference

### `CommandDef`

| Field | Type | Description |
|-------|------|-------------|
| `name` | `String` | Command name **(required)** |
| `about` | `String` | Short description shown in help |
| `args` | `Vec<ArgDef>` | List of arguments |
| `hidden` | `bool` | Hide from help output |
| `subcommands` | `Vec<CommandDef>` | Nested subcommands |
| `debug_only` | `bool` | Only include in debug builds |
| `aliases` | `Vec<String>` | Alternative names |

### `ArgDef`

| Field | Type | Description |
|-------|------|-------------|
| `name` | `String` | Argument identifier **(required)** |
| `short` | `char` | Short flag (e.g., `-v`) |
| `long` | `String` | Long flag (e.g., `--verbose`) |
| `help` | `String` | Help text |
| `value_name` | `String` | Placeholder for the value |
| `required` | `bool` | Mandatory argument |
| `num_args` | `String` | Number of values accepted |
| `action` | `String` | Action to perform |
| `default_value` | `String` | Default value |
| `conflicts_with` | `String` | Name of an incompatible argument |

### Supported `num_args` Values

| Value | Meaning |
|-------|---------|
| `"0.."` | Zero or more |
| `"1.."` | One or more |
| `"0..1"` | Zero or one |
| `"0..="` | Zero to `usize::MAX` |
| `"N"` | Exactly N (e.g., `"3"`) |

### Supported `action` Values

| Value | Clap Action |
|-------|-------------|
| `"set_true"` | `ArgAction::SetTrue` |
| `"set_false"` | `ArgAction::SetFalse` |
| `"append"` | `ArgAction::Append` |
| `"count"` | `ArgAction::Count` |
| *(default)* | `ArgAction::Set` |

## Safety & Linting

This crate:
- **Forbids** all unsafe code (`#![forbid(unsafe_code)]`)
- Passes Clippy with `all` warnings enabled
- Requires Rust 1.70 or later

## Notes

- **String Leaking**: The implementation intentionally leaks strings to `&'static str` to satisfy clap's lifetime requirements. This is acceptable for CLI tools that run once and exit.
- **Command Sorting**: Commands and subcommands are sorted alphabetically for consistent help output.
- **Debug-Only Commands**: Use `debug_only: true` to include commands only in debug builds (they are stripped from release builds via `#[cfg(not(debug_assertions))]`).

## License

MIT