diff options
| author | 2025-03-27 09:20:39 +0100 | |
|---|---|---|
| committer | 2025-03-27 09:20:39 +0100 | |
| commit | a4e784da8399c51d5eeb5783e6a485b960d5c1f9 (patch) | |
| tree | 4f848e95d695bddbf61b1dccce968443ebdfaf6d | |
| parent | Release 0.10.0 (diff) | |
| download | zig-clap-a4e784da8399c51d5eeb5783e6a485b960d5c1f9.tar.gz zig-clap-a4e784da8399c51d5eeb5783e6a485b960d5c1f9.tar.xz zig-clap-a4e784da8399c51d5eeb5783e6a485b960d5c1f9.zip | |
doc: Don't autogenerate the README
| -rw-r--r-- | README.md | 3 | ||||
| -rw-r--r-- | build.zig | 32 | ||||
| -rw-r--r-- | example/README.md.template | 129 |
3 files changed, 0 insertions, 164 deletions
| @@ -1,6 +1,3 @@ | |||
| 1 | <!--- | ||
| 2 | README.md is autogenerated. Please edit example/README.md.template instead. | ||
| 3 | --> | ||
| 4 | # zig-clap | 1 | # zig-clap |
| 5 | 2 | ||
| 6 | A simple and easy to use command line argument parser library for Zig. | 3 | A simple and easy to use command line argument parser library for 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 | ||
| 58 | fn 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 | |||
| 84 | const std = @import("std"); | 52 | const 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 | <!--- | ||
| 2 | README.md is autogenerated. Please edit example/README.md.template instead. | ||
| 3 | --> | ||
| 4 | # zig-clap | ||
| 5 | |||
| 6 | A simple and easy to use command line argument parser library for Zig. | ||
| 7 | |||
| 8 | ## Installation | ||
| 9 | |||
| 10 | Developers tend to either use | ||
| 11 | * The latest tagged release of Zig | ||
| 12 | * The latest build of Zigs master branch | ||
| 13 | |||
| 14 | Depending 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 | ||
| 20 | zig 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 | ||
| 23 | zig fetch --save git+https://github.com/Hejsil/zig-clap | ||
| 24 | ``` | ||
| 25 | |||
| 26 | Then add the following to `build.zig`: | ||
| 27 | |||
| 28 | ```zig | ||
| 29 | const clap = b.dependency("clap", .{{}}); | ||
| 30 | exe.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 | |||
| 48 | Automatically generated API Reference for the project can be found at | ||
| 49 | https://Hejsil.github.io/zig-clap. Note that Zig autodoc is in beta; the website | ||
| 50 | may be broken or incomplete. | ||
| 51 | |||
| 52 | ## Examples | ||
| 53 | |||
| 54 | ### `clap.parse` | ||
| 55 | |||
| 56 | The simplest way to use this library is to just call the `clap.parse` function. | ||
| 57 | |||
| 58 | ```zig | ||
| 59 | {s} | ||
| 60 | ``` | ||
| 61 | |||
| 62 | The result will contain an `args` field and a `positionals` field. `args` will have one field for | ||
| 63 | each non-positional parameter of your program. The name of the field will be the longest name of the | ||
| 64 | parameter. `positionals` will be a tuple with one field for each positional parameter. | ||
| 65 | |||
| 66 | The fields in `args` and `postionals` are typed. The type is based on the name of the value the | ||
| 67 | parameter takes. Since `--number` takes a `usize` the field `res.args.number` has the type `usize`. | ||
| 68 | |||
| 69 | Note that this is only the case because `clap.parsers.default` has a field called `usize` which | ||
| 70 | contains a parser that returns `usize`. You can pass in something other than `clap.parsers.default` | ||
| 71 | if you want some other mapping. | ||
| 72 | |||
| 73 | ```zig | ||
| 74 | {s} | ||
| 75 | ``` | ||
| 76 | |||
| 77 | ### Subcommands | ||
| 78 | |||
| 79 | There is an option for `clap.parse` and `clap.parseEx` called `terminating_positional`. It allows | ||
| 80 | for users of `clap` to implement subcommands in their cli application: | ||
| 81 | |||
| 82 | ```zig | ||
| 83 | {s} | ||
| 84 | ``` | ||
| 85 | |||
| 86 | ### `streaming.Clap` | ||
| 87 | |||
| 88 | The `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 | |||
| 95 | Currently, 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` | ||
| 101 | is 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 | |||