summaryrefslogtreecommitdiff
path: root/example
diff options
context:
space:
mode:
authorGravatar Jimmi Holst Christensen2025-03-27 09:20:39 +0100
committerGravatar Jimmi Holst Christensen2025-03-27 09:20:39 +0100
commita4e784da8399c51d5eeb5783e6a485b960d5c1f9 (patch)
tree4f848e95d695bddbf61b1dccce968443ebdfaf6d /example
parentRelease 0.10.0 (diff)
downloadzig-clap-a4e784da8399c51d5eeb5783e6a485b960d5c1f9.tar.gz
zig-clap-a4e784da8399c51d5eeb5783e6a485b960d5c1f9.tar.xz
zig-clap-a4e784da8399c51d5eeb5783e6a485b960d5c1f9.zip
doc: Don't autogenerate the README
Diffstat (limited to 'example')
-rw-r--r--example/README.md.template129
1 files changed, 0 insertions, 129 deletions
diff --git a/example/README.md.template b/example/README.md.template
deleted file mode 100644
index 4fe1d87..0000000
--- a/example/README.md.template
+++ /dev/null
@@ -1,129 +0,0 @@
1<!---
2README.md is autogenerated. Please edit example/README.md.template instead.
3-->
4# zig-clap
5
6A simple and easy to use command line argument parser library for Zig.
7
8## Installation
9
10Developers tend to either use
11* The latest tagged release of Zig
12* The latest build of Zigs master branch
13
14Depending on which developer you are, you need to run different `zig fetch` commands:
15
16```sh
17# Version of zig-clap that works with a tagged release of Zig
18# Replace `<REPLACE ME>` with the version of zig-clap that you want to use
19# See: https://github.com/Hejsil/zig-clap/releases
20zig fetch --save https://github.com/Hejsil/zig-clap/archive/refs/tags/<REPLACE ME>.tar.gz
21
22# Version of zig-clap that works with latest build of Zigs master branch
23zig fetch --save git+https://github.com/Hejsil/zig-clap
24```
25
26Then add the following to `build.zig`:
27
28```zig
29const clap = b.dependency("clap", .{{}});
30exe.root_module.addImport("clap", clap.module("clap"));
31```
32
33## Features
34
35* Short arguments `-a`
36 * Chaining `-abc` where `a` and `b` does not take values.
37 * Multiple specifications are tallied (e.g. `-v -v`).
38* Long arguments `--long`
39* Supports both passing values using spacing and `=` (`-a 100`, `-a=100`)
40 * Short args also support passing values with no spacing or `=` (`-a100`)
41 * This all works with chaining (`-ba 100`, `-ba=100`, `-ba100`)
42* Supports options that can be specified multiple times (`-e 1 -e 2 -e 3`)
43* Print help message from parameter specification.
44* Parse help message to parameter specification.
45
46## API Reference
47
48Automatically generated API Reference for the project can be found at
49https://Hejsil.github.io/zig-clap. Note that Zig autodoc is in beta; the website
50may be broken or incomplete.
51
52## Examples
53
54### `clap.parse`
55
56The simplest way to use this library is to just call the `clap.parse` function.
57
58```zig
59{s}
60```
61
62The result will contain an `args` field and a `positionals` field. `args` will have one field for
63each non-positional parameter of your program. The name of the field will be the longest name of the
64parameter. `positionals` will be a tuple with one field for each positional parameter.
65
66The fields in `args` and `postionals` are typed. The type is based on the name of the value the
67parameter takes. Since `--number` takes a `usize` the field `res.args.number` has the type `usize`.
68
69Note that this is only the case because `clap.parsers.default` has a field called `usize` which
70contains a parser that returns `usize`. You can pass in something other than `clap.parsers.default`
71if you want some other mapping.
72
73```zig
74{s}
75```
76
77### Subcommands
78
79There is an option for `clap.parse` and `clap.parseEx` called `terminating_positional`. It allows
80for users of `clap` to implement subcommands in their cli application:
81
82```zig
83{s}
84```
85
86### `streaming.Clap`
87
88The `streaming.Clap` is the base of all the other parsers. It's a streaming parser that uses an
89`args.Iterator` to provide it with arguments lazily.
90
91```zig
92{s}
93```
94
95Currently, this parser is the only parser that allows an array of `Param` that is generated at runtime.
96
97### `help`
98
99`help` prints a simple list of all parameters the program can take. It expects the `Id` to have a
100`description` method and an `value` method so that it can provide that in the output. `HelpOptions`
101is passed to `help` to control how the help message is printed.
102
103```zig
104{s}
105```
106
107```
108$ zig-out/bin/help --help
109 -h, --help
110 Display this help and exit.
111
112 -v, --version
113 Output version information and exit.
114```
115
116### `usage`
117
118`usage` prints a small abbreviated version of the help message. It expects the `Id` to have a
119`value` method so it can provide that in the output.
120
121```zig
122{s}
123```
124
125```
126$ zig-out/bin/usage --help
127[-hv] [--value <str>]
128```
129