blob: bbf5cb8e22a8da2a08318152a7f53ddf8e50b5ec (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
<!---
README.md is autogenerated. Please edit example/README.md.template instead.
-->
# 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` 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 non-positional parameter of your program. The name of the field will be the longest name of the
parameter. `positionals` will 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`
`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`
`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 <str>]
```
|
