# 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 `` 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/.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` does 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 {s} ``` The result will contain an `args` field and a `positionals` field. `args` will have one field for each none positional parameter of your program. The name of the field will be the longest name of the parameter. `positionals` be a tuple with one field for each positional parameter. The fields in `args` and `postionals` are typed. The type is based on the name of the value the parameter takes. Since `--number` takes a `usize` the field `res.args.number` has the type `usize`. Note that this is only the case because `clap.parsers.default` has a field called `usize` which contains a parser that returns `usize`. You can pass in something other than `clap.parsers.default` if you want some other mapping. ```zig {s} ``` ### Subcommands There is an option for `clap.parse` and `clap.parseEx` called `terminating_positional`. It allows for users of `clap` to implement subcommands in their cli application: ```zig {s} ``` ### `streaming.Clap` The `streaming.Clap` is the base of all the other parsers. It's a streaming parser that uses an `args.Iterator` to provide it with arguments lazily. ```zig {s} ``` Currently, this parser is the only parser that allows an array of `Param` that is generated at runtime. ### `help` The `help` prints a simple list of all parameters the program can take. It expects the `Id` to have a `description` method and an `value` method so that it can provide that in the output. `HelpOptions` is passed to `help` to control how the help message is printed. ```zig {s} ``` ``` $ zig-out/bin/help --help -h, --help Display this help and exit. -v, --version Output version information and exit. ``` ### `usage` The `usage` prints a small abbreviated version of the help message. It expects the `Id` to have a `value` method so it can provide that in the output. ```zig {s} ``` ``` $ zig-out/bin/usage --help [-hv] [--value ] ```