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:

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:

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:

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