example | ||
src | ||
.gitattributes | ||
.gitignore | ||
.travis.yml | ||
build.zig | ||
clap.zig | ||
download-zig.sh | ||
LICENSE | ||
README.md |
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
- Print help message from parameter specification.
- Parse help message to parameter specification.
Examples
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 std = @import("std");
const clap = @import("clap");
const debug = std.debug;
pub fn main() !void {
const allocator = std.heap.direct_allocator;
// First we specify what parameters our program can take.
const params = [_]clap.Param(u8){
clap.Param(u8){
.id = 'h',
.names = clap.Names{ .short = 'h', .long = "help" },
},
clap.Param(u8){
.id = 'n',
.names = clap.Names{ .short = 'n', .long = "number" },
.takes_value = true,
},
clap.Param(u8){
.id = 'f',
.takes_value = true,
},
};
// We then initialize an argument iterator. We will use the OsIterator as it nicely
// wraps iterating over arguments the most efficient way on each os.
var iter = clap.args.OsIterator.init(allocator);
defer iter.deinit();
// Consume the exe arg.
const exe = try iter.next();
// Finally we initialize our streaming parser.
var parser = clap.StreamingClap(u8, clap.args.OsIterator){
.params = params,
.iter = &iter,
};
// Because we use a streaming parser, we have to consume each argument parsed individually.
while (try parser.next()) |arg| {
// arg.param will point to the parameter which matched the argument.
switch (arg.param.id) {
'h' => debug.warn("Help!\n"),
'n' => debug.warn("--number = {}\n", arg.value.?),
// arg.value == null, if arg.param.takes_value == false.
// Otherwise, arg.value is the value passed with the argument, such as "-a=10"
// or "-a 10".
'f' => debug.warn("{}\n", arg.value.?),
else => unreachable,
}
}
}
ComptimeClap
The ComptimeClap
is a wrapper for StreamingClap
, which parses all the arguments and makes
them available through three functions (flag
, option
, positionals
).
const std = @import("std");
const clap = @import("clap");
const debug = std.debug;
pub fn main() !void {
const allocator = std.heap.direct_allocator;
// 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.Param(clap.Help){
.takes_value = true,
},
};
// We then initialize an argument iterator. We will use the OsIterator as it nicely
// wraps iterating over arguments the most efficient way on each os.
var iter = clap.args.OsIterator.init(allocator);
defer iter.deinit();
// Consume the exe arg.
const exe = try iter.next();
// Finally we can parse the arguments
var args = try clap.ComptimeClap(clap.Help, params).parse(allocator, clap.args.OsIterator, &iter);
defer args.deinit();
if (args.flag("--help"))
debug.warn("--help\n");
if (args.option("--number")) |n|
debug.warn("--number = {}\n", n);
for (args.positionals()) |pos|
debug.warn("{}\n", pos);
}
The data structure returned from this parser has lookup speed on par with array access (arr[i]
)
and validates that the strings you pass to option
and flag
are actually parameters that the
program can take:
const std = @import("std");
const clap = @import("clap");
pub fn main() !void {
const allocator = std.heap.direct_allocator;
const params = [_]clap.Param(void){clap.Param(void){
.names = clap.Names{ .short = 'h', .long = "help" },
}};
var iter = clap.args.OsIterator.init(allocator);
defer iter.deinit();
const exe = try iter.next();
var args = try clap.ComptimeClap(void, params).parse(allocator, clap.args.OsIterator, &iter);
defer args.deinit();
_ = args.flag("--helps");
}
zig-clap/src/comptime.zig:109:17: error: --helps is not a parameter.
@compileError(name ++ " is not a parameter.");
^
zig-clap/src/comptime.zig:77:45: note: called from here
const param = comptime findParam(name);
^
zig-clap/example/comptime-clap-error.zig:18:18: note: called from here
_ = args.flag("--helps");
^
Ofc, this limits you to parameters that are comptime known.
help
The help
, helpEx
and helpFull
are functions for printing a simple list of all parameters the
program can take.
const std = @import("std");
const clap = @import("clap");
pub fn main() !void {
const stderr_file = try std.io.getStdErr();
var stderr_out_stream = stderr_file.outStream();
const stderr = &stderr_out_stream.stream;
// 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.
try clap.help(
stderr,
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,
},
);
}
-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.