summaryrefslogtreecommitdiff
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
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
-rw-r--r--README.md3
-rw-r--r--build.zig32
-rw-r--r--example/README.md.template129
3 files changed, 0 insertions, 164 deletions
diff --git a/README.md b/README.md
index a9d2b8a..fbc19e4 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,3 @@
1<!---
2README.md is autogenerated. Please edit example/README.md.template instead.
3-->
4# zig-clap 1# zig-clap
5 2
6A simple and easy to use command line argument parser library for Zig. 3A simple and easy to use command line argument parser library for Zig.
diff --git a/build.zig b/build.zig
index 3b88e47..eed582d 100644
--- a/build.zig
+++ b/build.zig
@@ -42,43 +42,11 @@ pub fn build(b: *std.Build) void {
42 }); 42 });
43 docs_step.dependOn(&install_docs.step); 43 docs_step.dependOn(&install_docs.step);
44 44
45 const readme_step = b.step("readme", "Remake README.");
46 const readme = readMeStep(b);
47 readme.dependOn(example_step);
48 readme_step.dependOn(readme);
49
50 const all_step = b.step("all", "Build everything and runs all tests"); 45 const all_step = b.step("all", "Build everything and runs all tests");
51 all_step.dependOn(test_step); 46 all_step.dependOn(test_step);
52 all_step.dependOn(example_step); 47 all_step.dependOn(example_step);
53 all_step.dependOn(readme_step);
54 48
55 b.default_step.dependOn(all_step); 49 b.default_step.dependOn(all_step);
56} 50}
57 51
58fn readMeStep(b: *std.Build) *std.Build.Step {
59 const s = b.allocator.create(std.Build.Step) catch unreachable;
60 s.* = std.Build.Step.init(.{
61 .id = .custom,
62 .name = "ReadMeStep",
63 .owner = b,
64 .makeFn = struct {
65 fn make(step: *std.Build.Step, _: std.Build.Step.MakeOptions) anyerror!void {
66 @setEvalBranchQuota(10000);
67 _ = step;
68 const file = try std.fs.cwd().createFile("README.md", .{});
69 const stream = file.writer();
70 try stream.print(@embedFile("example/README.md.template"), .{
71 @embedFile("example/simple.zig"),
72 @embedFile("example/simple-ex.zig"),
73 @embedFile("example/subcommands.zig"),
74 @embedFile("example/streaming-clap.zig"),
75 @embedFile("example/help.zig"),
76 @embedFile("example/usage.zig"),
77 });
78 }
79 }.make,
80 });
81 return s;
82}
83
84const std = @import("std"); 52const std = @import("std");
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