Note: This branch targets the master branch of zig. See supported versions table.
The ultimate zig library for seamless command-line parsing. Effortlessly handles options, subcommands, and custom arguments with ease.
Inspired by clap-rs and andrewrk/ziglang: src-self-hosted/arg.zig
yazap | Zig |
---|---|
main | master |
0.5.1 |
0.12.0 , 0.12.1 and 0.13.0 |
<= 0.5.0 |
Not supported to any |
-
Options (short and long):
- Providing values with
=
, space, or no space (-f=value
,-f value
,-fvalue
). - Supports delimiter-separated values with
=
or without space (-f=v1,v2,v3
,-fv1:v2:v3
). - Chaining multiple short boolean options (
-abc
). - Providing values and delimiter-separated values for multiple chained options using
=
(-abc=val
,-abc=v1,v2,v3
). - Specifying an option multiple times (
-a 1 -a 2 -a 3
).
- Providing values with
-
Positional arguments:
- Supports positional arguments alongside options for more flexible command-line inputs. For example:
command <positional_arg>
command <arg1> <arg2> <arg3>
- Supports positional arguments alongside options for more flexible command-line inputs. For example:
-
Nested subcommands:
- Organize commands with nested subcommands for a structured command-line interface. For example:
command subcommand
command subcommand subsubcommand
- Organize commands with nested subcommands for a structured command-line interface. For example:
-
Automatic help handling and generation
-
Custom Argument definition:
- Define custom Argument types for specific application requirements.
- Does not support delimiter-separated values using space (
-f v1,v2,v3
). - Does not support providing value and delimiter-separated values for multiple
chained options using space (
-abc value, -abc v1,v2,v3
).
- Run the following command:
zig fetch --save git+https://github.com/prajwalch/yazap
- Add the following to
build.zig
:
const yazap = b.dependency("yazap", .{});
exe.root_module.addImport("yazap", yazap.module("yazap"));
For detailed and comprehensive documentation, please visit this link.
The examples can be found here. To build all of them, run the following command on your terminal:
$ zig build examples
After the compilation finishes, you can run each example by executing the corresponding binary:
$ ./zig-out/bin/example_name
To view the usage and available options for each example, you can use -h
or
--help
flag:
$ ./zig-out/bin/example_name --help
To begin using yazap
, the first step is to create an instance of
App by calling
App.init(allocator, "Your app name", "optional description")
. This function
internally creates a root command for your application.
var app = App.init(allocator, "myls", "My custom ls");
defer app.deinit();
The App itself does not provide any methods for adding arguments to your command. Its main purpose is to initialize the library, invoke the parser, and free associated structures. To add arguments and subcommands, you'll need to use the root command.
To obtain the root command, simply call App.rootCommand()
, which returns a
pointer to it. This gives you access to the core command of your application.
var myls = app.rootCommand();
Once you have obtained the root command, you can proceed to arguments using the
provided methods in the Command
. For a complete list of available methods,
refer to the Command API
documentation.
try myls.addArg(Arg.positional("FILE", null, null));
try myls.addArg(Arg.booleanOption("all", 'a', "Don't ignore the hidden directories"));
try myls.addArg(Arg.booleanOption("recursive", 'R', "List subdirectories recursively"));
try myls.addArg(Arg.booleanOption("one-line", '1', null));
try myls.addArg(Arg.booleanOption("size", 's', null));
try myls.addArg(Arg.booleanOption("version", null, null));
try myls.addArg(Arg.singleValueOption("ignore", 'I', null));
try myls.addArg(Arg.singleValueOption("hide", null, null));
try myls.addArg(Arg.singleValueOptionWithValidValues("color", 'C', null, &[_][]const u8{
"always",
"auto",
"never",
}));
Alternatively, you can add multiple arguments in a single function call using
Command.addArgs()
:
try myls.addArgs(&[_]Arg {
Arg.positional("FILE", null, null),
Arg.booleanOption("all", 'a', "Don't ignore the hidden directories"),
Arg.booleanOption("recursive", 'R', "List subdirectories recursively"),
Arg.booleanOption("one-line", '1', null),
Arg.booleanOption("size", 's', null),
Arg.booleanOption("version", null, null),
Arg.singleValueOption("ignore", 'I', null),
Arg.singleValueOption("hide", null, null),
Arg.singleValueOptionWithValidValues("color", 'C', null, &[_][]const u8{
"always",
"auto",
"never",
}),
});
To create a subcommand, you can use App.createCommand("name", "optional description")
.
Once you have created a subcommand, you can add its own arguments and subcommands
just like the root command then add it to the root command using Command.addSubcommand()
.
var update_cmd = app.createCommand("update", "Update the app or check for new updates");
try update_cmd.addArg(Arg.booleanOption("check-only", null, "Only check for new update"));
try update_cmd.addArg(Arg.singleValueOptionWithValidValues("branch", 'b', "Branch to update", &[_][]const u8{
"stable",
"nightly",
"beta"
}));
try myls.addSubcommand(update_cmd);
Once you have finished adding arguments and subcommands, call App.parseProcess()
to start the parsing process. This function internally utilizes
std.process.argsAlloc
to obtain the raw arguments. Alternatively, you can use App.parseFrom()
and
pass your own raw arguments, which can be useful during testing. Both functions
return a constant pointer to ArgMatches
.
const matches = try app.parseProcess();
if (matches.containsArg("version")) {
log.info("v0.1.0", .{});
return;
}
if (matches.getSingleValue("FILE")) |f| {
log.info("List contents of {f}");
return;
}
if (matches.subcommandMatches("update")) |update_cmd_matches| {
if (update_cmd_matches.containsArg("check-only")) {
std.log.info("Check and report new update", .{});
return;
}
if (update_cmd_matches.getSingleValue("branch")) |branch| {
std.log.info("Branch to update: {s}", .{branch});
return;
}
return;
}
if (matches.containsArg("all")) {
log.info("show all", .{});
return;
}
if (matches.containsArg("recursive")) {
log.info("show recursive", .{});
return;
}
if (matches.getSingleValue("ignore")) |pattern| {
log.info("ignore pattern = {s}", .{pattern});
return;
}
if (matches.containsArg("color")) {
const when = matches.getSingleValue("color").?;
log.info("color={s}", .{when});
return;
}
The handling of -h
or --help
option and the automatic display of usage
information are taken care by the library. However, if you need to manually
display the help information, there are two functions available: App.displayHelp()
and App.displaySubcommandHelp()
.
-
App.displayHelp()
prints the help information for the root command, providing a simple way to display the overall usage and description of the application. -
On the other hand,
App.displaySubcommandHelp()
queries the sepecifed subcommand on the command line and displays its specific usage information.
if (!matches.containsArgs()) {
try app.displayHelp();
return;
}
if (matches.subcommandMatches("update")) |update_cmd_matches| {
if (!update_cmd_matches.containsArgs()) {
try app.displaySubcommandHelp();
return;
}
}
const std = @import("std");
const yazap = @import("yazap");
const allocator = std.heap.page_allocator;
const log = std.log;
const App = yazap.App;
const Arg = yazap.Arg;
pub fn main() anyerror!void {
var app = App.init(allocator, "myls", "My custom ls");
defer app.deinit();
var myls = app.rootCommand();
var update_cmd = app.createCommand("update", "Update the app or check for new updates");
try update_cmd.addArg(Arg.booleanOption("check-only", null, "Only check for new update"));
try update_cmd.addArg(Arg.singleValueOptionWithValidValues("branch", 'b', "Branch to update", &[_][]const u8{
"stable",
"nightly",
"beta"
}));
try myls.addSubcommand(update_cmd);
try myls.addArg(Arg.positional("FILE", null, null));
try myls.addArg(Arg.booleanOption("all", 'a', "Don't ignore the hidden directories"));
try myls.addArg(Arg.booleanOption("recursive", 'R', "List subdirectories recursively"));
try myls.addArg(Arg.booleanOption("one-line", '1', null));
try myls.addArg(Arg.booleanOption("size", 's', null));
try myls.addArg(Arg.booleanOption("version", null, null));
try myls.addArg(Arg.singleValueOption("ignore", 'I', null));
try myls.addArg(Arg.singleValueOption("hide", null, null));
try myls.addArg(Arg.singleValueOptionWithValidValues("color", 'C', null, &[_][]const u8{
"always",
"auto",
"never",
}));
const matches = try app.parseProcess();
if (!matches.containsArgs()) {
try app.displayHelp();
return;
}
if (matches.containsArg("version")) {
log.info("v0.1.0", .{});
return;
}
if (matches.getSingleValue("FILE")) |f| {
log.info("List contents of {f}");
return;
}
if (matches.subcommandMatches("update")) |update_cmd_matches| {
if (!update_cmd_matches.containsArgs()) {
try app.displaySubcommandHelp();
return;
}
if (update_cmd_matches.containsArg("check-only")) {
std.log.info("Check and report new update", .{});
return;
}
if (update_cmd_matches.getSingleValue("branch")) |branch| {
std.log.info("Branch to update: {s}", .{branch});
return;
}
return;
}
if (matches.containsArg("all")) {
log.info("show all", .{});
return;
}
if (matches.containsArg("recursive")) {
log.info("show recursive", .{});
return;
}
if (matches.getSingleValue("ignore")) |pattern| {
log.info("ignore pattern = {s}", .{pattern});
return;
}
if (matches.containsArg("color")) {
const when = matches.getSingleValue("color").?;
log.info("color={s}", .{when});
return;
}
}
- Hejsil/zig-clap - Simple command line argument parsing library
- winksaville/zig-parse-args - Parse command line arguments
- MasterQ32/zig-args - Simple-to-use argument parser with struct-based config