zig-clap

# zig-clap

A simple and easy to use command line argument parser library for Zig.

## Installation

Developers tend to either use

- The latest tagged release of Zig
- The latest build of Zigs master branch

Depending on which developer you are, you need to run different `zig fetch` commands:

```sh
# Version of zig-clap that works with a tagged release of Zig
# Replace `<REPLACE ME>` with the version of zig-clap that you want to use
# See: https://github.com/Hejsil/zig-clap/releases
zig fetch --save https://github.com/Hejsil/zig-clap/archive/refs/tags/<REPLACE ME>.tar.gz

# Version of zig-clap that works with latest build of Zigs master branch
zig fetch --save git+https://github.com/Hejsil/zig-clap
```

Then add the following to `build.zig`:

```zig
const clap = b.dependency("clap", .{});
exe.root_module.addImport("clap", clap.module("clap"));
```

## Features

- Short arguments `-a`
  - Chaining `-abc` where `a` and `b` do not take values.
  - Multiple specifications are tallied (e.g. `-v -v`).
- Long arguments `--long`
- Supports both passing values using spacing and `=` (`-a 100`, `-a=100`)
  - Short args also support passing values with no spacing or `=` (`-a100`)
  - This all works with chaining (`-ba 100`, `-ba=100`, `-ba100`)
- Supports options that can be specified multiple times (`-e 1 -e 2 -e 3`)
- Print help message from parameter specification.
- Parse help message to parameter specification.

## API Reference

Automatically generated API Reference for the project can be found at
https://Hejsil.github.io/zig-clap. Note that Zig autodoc is in beta; the website may be broken or
incomplete.

## Examples

### `clap.parse`

The simplest way to use this library is to just call the `clap.parse` function.

```zig
pub fn main(init: std.process.Init) !void {
    // First we specify what parameters our program can take.
    // We can use `parseParamsComptime` to parse a string into an array of `Param(Help)`.
    const params = comptime clap.parseParamsComptime(
        \\-h, --help             Display this help and exit.
        \\-n, --number <usize>   An option parameter, which takes a value.
        \\-s, --string <str>...  An option parameter which can be specified multiple times.
        \\<str>...
        \\
    );

    // Initialize our diagnostics, which can be used for reporting useful errors.
    // This is optional. You can also pass `.{}` to `clap.parse` if you don't
    // care about the extra information `Diagnostics` provides.
    var diag = clap.Diagnostic{};
    var res = clap.parse(clap.Help, &params, clap.parsers.default, init.minimal.args, .{
        .diagnostic = &diag,
        .allocator = init.gpa,
    }) catch |err| {
        // Report useful error and exit.
        try diag.reportToFile(init.io, .stderr(), err);
        return err;
    };
    defer res.deinit();

    if (res.args.help != 0)
        std.debug.print("--help\n", .{});
    if (res.args.number) |n|
        std.debug.print("--number = {}\n", .{n});
    for (