blob: bcd3774f5ac3ff0d651a655e941606ad38fc3906 (
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
130
131
|
<!---
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 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 <str>]
```
|
