1/Hejsil/clap v0.6
zig-clap
A simple and easy to use command line argument parser library for Zig.
Features
- Short arguments
-a
- Chaining
-abc
wherea
andb
does not take values.
- Chaining
- 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
)
- Short args also support passing values with no spacing or
- 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.
Examples
clap.parse
The simplest way to use this library is to just call the clap.parse
function.
const clap = @import("clap");
const std = @import("std");
const debug = std.debug;
const io = std.io;
pub fn main() !void {
// First we specify what parameters our program can take.
// We can use `parseParam` to parse a string to a `Param(Help)`
const params = comptime [_]clap.Param(clap.Help){
clap.parseParam("-h, --help Display this help and exit. ") catch unreachable,
clap.parseParam("-n, --number <NUM> An option parameter, which takes a value.") catch unreachable,
clap.parseParam("-s, --string <STR>... An option parameter which can be specified multiple times.") catch unreachable,
clap.parseParam("<POS>...") catch unreachable,
};
// Initalize our diagnostics, which can be used for reporting useful errors.
// This is optional. You can also pass `.{}` to `clap.parse` if you don't
// care about the extra information `Diagnostics` provides.
var diag = clap.Diagnostic{};
var args = clap.parse(clap.Help, ¶ms, .{ .diagnostic = &diag }) catch |err| {
// Report useful error and exit
diag.report(io.getStdErr().writer(), err) catch {};
return err;
};
defer args.deinit();
if (args.flag("--help"))
debug.print("--help\n", .{});
if (args.option("--number")) |n|
debug.print("--number = {s}\n", .{n});
for (args.options("--string")) |s|
debug.print("--string = {s}\n", .{s});
for (args.positionals()) |pos|
debug.print("{s}\n", .{pos});
}
The data structure returned has lookup speed on par with array access (arr[i]
) and validates
that the strings you pass to option
, options
and flag
are actually parameters that the
program can take:
const clap = @import("clap");
const std = @import("std");
pub fn main() !void {
const params = comptime [_]clap.Param(clap.Help){
clap.parseParam("-h, --help Display this help and exit.") catch unreachable,
};
var args = try clap.parse(clap.Help, ¶ms, .{});
defer args.deinit();
_ = args.flag("--helps");
}
zig-clap/clap/comptime.zig:109:17: error: --helps is not a parameter.
@compileError(name ++ " is not a parameter.");
^
zig-clap/clap/comptime.zig:77:45: note: called from here
const param = comptime findParam(name);
^
zig-clap/clap.zig:238:31: note: called from here
return a.clap.flag(name);
^
zig-clap/example/simple-error.zig:16:18: note: called from here
_ = args.flag("--helps");
There is also a parseEx
variant that takes an argument iterator.
StreamingClap
The StreamingClap
is the base of all the other parsers. It's a streaming parser that uses an
args.Iterator
to provide it with arguments lazily.
const clap = @import("clap");
const std = @import("std");
const debug = std.debug;
const io = std.io;
const process = std.process;
pub fn main() !void {
const allocator = std.heap.page_allocator;
// First we specify what parameters our program can take.
const params = [_]clap.Param(u8){
.{
.id = 'h',
.names = .{ .short = 'h', .long = "help" },
},
.{
.id = 'n',
.names = .{ .short = 'n', .long = "number" },
.takes_value = .one,
},
.{ .id = 'f', .takes_value = .one },
};
var iter = try process.ArgIterator.initWithAllocator(allocator);
defer iter.deinit();
// Skip exe argument
_ = iter.next();
// Initalize our diagnostics, which can be used for reporting useful errors.
// This is optional. You can also leave the `diagnostic` field unset if you
// don't care about the extra information `Diagnostic` provides.
var diag = clap.Diagnostic{};
var parser = clap.StreamingClap(u8, process.ArgIterator){
.params = ¶ms,
.iter = &iter,
.diagnostic = &diag,
};
// Because we use a streaming parser, we have to consume each argument parsed individually.
while (parser.next() catch |err| {
// Report useful error and exit
diag.report(io.getStdErr().writer(), err) catch {};
return err;
}) |arg| {
// arg.param will point to the parameter which matched the argument.
switch (arg.param.id) {
'h' => debug.print("Help!\n", .{}),
'n' => debug.print("--number = {s}\n", .{arg.value.?}),
// arg.value == null, if arg.param.takes_value == .none.
// Otherwise, arg.value is the value passed with the argument, such as "-a=10"
// or "-a 10".
'f' => debug.print("{s}\n", .{arg.value.?}),
else => unreachable,
}
}
}
Currently, this parser is the only parser that allows an array of Param
that
is generated at runtime.
help
The help
, helpEx
and helpFull
are functions for printing a simple list of all parameters the
program can take.
const clap = @import("clap");
const std = @import("std");
pub fn main() !void {
const params = comptime [_]clap.Param(clap.Help){
clap.parseParam("-h, --help Display this help and exit. ") catch unreachable,
clap.parseParam("-v, --version Output version information and exit.") catch unreachable,
};
var args = try clap.parse(clap.Help, ¶ms, .{});
defer args.deinit();
// clap.help is a function that can print a simple help message, given a
// slice of Param(Help). There is also a helpEx, which can print a
// help message for any Param, but it is more verbose to call.
if (args.flag("--help"))
return clap.help(std.io.getStdErr().writer(), ¶ms);
}
$ zig-out/bin/help --help
-h, --help Display this help and exit.
-v, --version Output version information and exit.
The help
functions are the simplest to call. It only takes an OutStream
and a slice of
Param(Help)
.
The helpEx
is the generic version of help
. It can print a help message for any
Param
give that the caller provides functions for getting the help and value strings.
The helpFull
is even more generic, allowing the functions that get the help and value strings
to return errors and take a context as a parameter.
usage
The usage
, usageEx
and usageFull
are functions for printing a small abbreviated version
of the help message.
const clap = @import("clap");
const std = @import("std");
pub fn main() !void {
const params = comptime [_]clap.Param(clap.Help){
clap.parseParam("-h, --help Display this help and exit. ") catch unreachable,
clap.parseParam("-v, --version Output version information and exit. ") catch unreachable,
clap.parseParam(" --value <N> An option parameter, which takes a value.") catch unreachable,
};
var args = try clap.parse(clap.Help, ¶ms, .{});
defer args.deinit();
// clap.usage is a function that can print a simple usage message, given a
// slice of Param(Help). There is also a usageEx, which can print a
// usage message for any Param, but it is more verbose to call.
if (args.flag("--help"))
return clap.usage(std.io.getStdErr().writer(), ¶ms);
}
$ zig-out/bin/usage --help
[-hv] [--value <N>]
Package Contents
- example/simple.zig
- example/streaming-clap.zig
- example/help.zig
- example/README.md.template
- example/simple-ex.zig
- example/usage.zig
- example/simple-error.zig
- gyro.zzz
- .gitattributes
- LICENSE
- .github/workflows/main.yml
- .github/dependabot.yml
- .github/FUNDING.yml
- build.zig
- README.md
- clap.zig
- zig.mod
- clap/comptime.zig
- clap/args.zig
- clap/streaming.zig
- .gitignore
History
Published On | Tree @ Commit | Size | |
---|---|---|---|
v0.51 | Thu, 16 Nov 2023 11:01:30 UTC | Tree | 99.549 KB |
v0.50 | Fri, 10 Nov 2023 08:45:18 UTC | Tree | 99.534 KB |
v0.49 | Sun, 10 Sep 2023 19:08:14 UTC | Tree | 99.466 KB |
v0.48 | Thu, 03 Aug 2023 07:37:04 UTC | Tree | 98.468 KB |
v0.47 | Tue, 27 Jun 2023 07:07:26 UTC | Tree | 98.463 KB |
v0.46 | Thu, 22 Jun 2023 07:26:05 UTC | Tree | 98.588 KB |
v0.45 | Sun, 18 Jun 2023 11:44:37 UTC | Tree | 98.584 KB |
v0.44 | Thu, 15 Jun 2023 07:53:18 UTC | Tree | 98.588 KB |
v0.43 | Mon, 17 Apr 2023 06:56:26 UTC | Tree | 97.907 KB |
v0.42 | Fri, 14 Apr 2023 06:39:03 UTC | Tree | 97.921 KB |
v0.41 | Sun, 02 Apr 2023 11:10:43 UTC | Tree | 97.779 KB |
v0.40 | Mon, 20 Mar 2023 08:25:54 UTC | Tree | 97.255 KB |
v0.39 | Sun, 19 Mar 2023 10:46:12 UTC | Tree | 97.249 KB |
v0.38 | Mon, 06 Mar 2023 22:26:36 UTC | Tree | 97.108 KB |
v0.37 | Wed, 01 Mar 2023 14:49:20 UTC | Tree | 97.143 KB |
v0.36 | Tue, 28 Feb 2023 15:15:17 UTC | Tree | 97.143 KB |
v0.35 | Sun, 26 Feb 2023 18:05:59 UTC | Tree | 97.293 KB |
v0.34 | Wed, 22 Feb 2023 08:38:03 UTC | Tree | 97.216 KB |
v0.33 | Mon, 06 Feb 2023 15:53:26 UTC | Tree | 97.206 KB |
v0.32 | Mon, 06 Feb 2023 08:13:29 UTC | Tree | 97.204 KB |
v0.31 | Sun, 05 Feb 2023 21:22:11 UTC | Tree | 97.226 KB |
v0.30 | Thu, 12 Jan 2023 18:50:08 UTC | Tree | 97.097 KB |
v0.29 | Wed, 04 Jan 2023 09:52:23 UTC | Tree | 97.086 KB |
v0.28 | Tue, 20 Dec 2022 13:11:39 UTC | Tree | 97.086 KB |
v0.27 | Fri, 09 Dec 2022 10:04:50 UTC | Tree | 97.104 KB |
v0.26 | Fri, 09 Dec 2022 09:50:04 UTC | Tree | 97.129 KB |
v0.25 | Thu, 01 Dec 2022 08:35:23 UTC | Tree | 97.288 KB |
v0.24 | Tue, 22 Nov 2022 13:51:54 UTC | Tree | 97.276 KB |
v0.23 | Tue, 15 Nov 2022 10:18:15 UTC | Tree | 97.253 KB |
v0.22 | Tue, 08 Nov 2022 12:47:42 UTC | Tree | 97.497 KB |
v0.21 | Tue, 01 Nov 2022 18:12:55 UTC | Tree | 97.497 KB |
v0.20 | Mon, 03 Oct 2022 10:57:15 UTC | Tree | 97.497 KB |
v0.19 | Mon, 03 Oct 2022 10:46:46 UTC | Tree | 97.416 KB |
v0.18 | Sun, 18 Sep 2022 17:07:01 UTC | Tree | 97.411 KB |
v0.17 | Thu, 25 Aug 2022 16:08:49 UTC | Tree | 97.415 KB |
v0.16 | Thu, 28 Jul 2022 12:50:37 UTC | Tree | 96.222 KB |
v0.15 | Mon, 25 Jul 2022 16:16:22 UTC | Tree | 95.982 KB |
v0.14 | Fri, 22 Jul 2022 09:01:18 UTC | Tree | 94.387 KB |
v0.13 | Thu, 28 Apr 2022 17:00:50 UTC | Tree | 94.157 KB |
v0.12 | Wed, 30 Mar 2022 20:04:24 UTC | Tree | 93.988 KB |
v0.11 | Wed, 30 Mar 2022 19:57:53 UTC | Tree | 93.854 KB |
v0.10 | Thu, 24 Mar 2022 10:08:46 UTC | Tree | 75.386 KB |
v0.9 | Wed, 23 Mar 2022 20:48:24 UTC | Tree | 75.237 KB |
v0.8 | Mon, 21 Mar 2022 22:03:53 UTC | Tree | 68.282 KB |
v0.7 | Wed, 09 Mar 2022 17:12:42 UTC | Tree | 67.399 KB |
v0.6 | Wed, 02 Mar 2022 16:56:42 UTC | Tree | 68.271 KB |
v0.5 | Fri, 25 Feb 2022 18:48:44 UTC | Tree | 68.278 KB |
v0.4 | Fri, 25 Feb 2022 18:44:33 UTC | Tree | 67.327 KB |
v0.3 | Tue, 22 Feb 2022 18:19:45 UTC | Tree | 68.278 KB |
v0.2 | Thu, 03 Feb 2022 21:00:17 UTC | Tree | 68.104 KB |
v0.1 | Thu, 03 Feb 2022 20:53:55 UTC | Tree | 68.116 KB |