From a4e784da8399c51d5eeb5783e6a485b960d5c1f9 Mon Sep 17 00:00:00 2001 From: Jimmi Holst Christensen Date: Thu, 27 Mar 2025 09:20:39 +0100 Subject: doc: Don't autogenerate the README --- README.md | 3 -- build.zig | 32 ----------- example/README.md.template | 129 --------------------------------------------- 3 files changed, 164 deletions(-) delete mode 100644 example/README.md.template diff --git a/README.md b/README.md index a9d2b8a..fbc19e4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,3 @@ - # zig-clap A 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 { }); docs_step.dependOn(&install_docs.step); - const readme_step = b.step("readme", "Remake README."); - const readme = readMeStep(b); - readme.dependOn(example_step); - readme_step.dependOn(readme); - const all_step = b.step("all", "Build everything and runs all tests"); all_step.dependOn(test_step); all_step.dependOn(example_step); - all_step.dependOn(readme_step); b.default_step.dependOn(all_step); } -fn readMeStep(b: *std.Build) *std.Build.Step { - const s = b.allocator.create(std.Build.Step) catch unreachable; - s.* = std.Build.Step.init(.{ - .id = .custom, - .name = "ReadMeStep", - .owner = b, - .makeFn = struct { - fn make(step: *std.Build.Step, _: std.Build.Step.MakeOptions) anyerror!void { - @setEvalBranchQuota(10000); - _ = step; - const file = try std.fs.cwd().createFile("README.md", .{}); - const stream = file.writer(); - try stream.print(@embedFile("example/README.md.template"), .{ - @embedFile("example/simple.zig"), - @embedFile("example/simple-ex.zig"), - @embedFile("example/subcommands.zig"), - @embedFile("example/streaming-clap.zig"), - @embedFile("example/help.zig"), - @embedFile("example/usage.zig"), - }); - } - }.make, - }); - return s; -} - 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 @@ - -# 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 `` 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/.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 ] -``` - -- cgit v1.2.3