saving

README.md

@@ -0,0 +1,101 @@
+# 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
+```