# zargs

A compile-time argument parser for Zig, hybrid mode, you can define structs whenever/wherever.

And get nice help info, but you also get the ability to arbitrarily parse structs at run time.

## Motivation

!here are two main ways people like to parse arguments, and they both suck in different ways.

1. predefine argv structure and parse state in one step (like python argparse)
2. game engine style for each place in the code that needs an argument loop over args and look for the argument you want

2 is very flexible, 1 is not.

this one lets you do it any way you wish or even redefine the argument parsing structure and 
still generate a helpful text using help().

Ai generated README with examples below.

## Usage

Define a config struct with default values and optional metadata:

```zig
const zargs = @import("zargs");

const Config = struct {
    input: []const u8 = "input.txt",
    output: []const u8 = "output.txt",
    verbose: bool = false,
    format: Format = .json,
    max_size: u32 = 1024,
    tags: []const []const u8 = &[_][]const u8{},

    pub const Format = enum { json, xml, csv };

    pub const meta = .{
        .input = .{ .short = 'i', .help = "Input file path" },
        .output = .{ .short = 'o', .help = "Output file path" },
        .verbose = .{ .short = 'v', .help = "Enable verbose output" },
        .format = .{ .help = "Output format" },
        .max_size = .{ .help = "Maximum file size in KB" },
        .tags = .{ .help = "Tags to filter (can specify multiple)" },
    };
};
```

Then parse it:

```zig
const config = try zargs.parse(Config, allocator);
defer zargs.shutdown();

if (zargs.isHelp(allocator)) {
    const help = try zargs.getUsageAlloc(allocator, "my-program");
    defer allocator.free(help);
    std.debug.print("{s}", .{help});
    return;
}
```

This gives you:

```
my-program --input data.csv -v --format csv --max-size 2048 --tags prod,staging
```

## Multi-Module Parsing

Multiple config structs can share the same argument list. Each call to `parse` pulls out the fields it recognizes:

```zig
const graphics = try zargs.parse(GraphicsConfig, allocator);
const audio = try zargs.parse(AudioConfig, allocator);
const engine = try zargs.parse(EngineConfig, allocator);
```

Help output combines all registered modules.

## Metadata Options

Each field in `pub const meta` supports:

| Field      | Type       | Description                        |
|------------|------------|------------------------------------|
| `short`    | `u8`       | Single-character short flag        |
| `help`     | `[]const u8` | Description shown in help text  |
| `name`     | `[]const u8` | Override the generated flag name |
| `required` | `bool`     | Mark the argument as required      |

## Building

Requires Zig 0.15.2 or later.

```
zig build test              # run unit tests
zig build examples          # build examples
zig build run-file-processor -- --help
zig build run-multi-module -- --help
```