Yazap

Note This branch targets the master branch of zig. Use v0.9.x-v0.10.x branch if you're using an older versions.

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

Key Features:

• 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).

• Positional arguments:

  • Supports positional arguments alongside options for more flexible command-line inputs. For example:
    • command <positional_arg>
    • command <arg1> <arg2> <arg3>

• Nested subcommands:

  • Organize commands with nested subcommands for a structured command-line interface. For example:
    • command subcommand
    • command subcommand subsubcommand

• Automatic help handling and generation

• Custom Argument definition:

  • Define custom Argument types for specific application requirements.

Limitations:

• 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).

Installing

Requires zig v0.12.x.

1. Initialize your project as a repository (if it hasn't been initilized already) by running git init.

2. Create a directory named libs in the root of your project.

3. Add the yazap library as submodule by running the following command:

   git submodule add https://github.com/PrajwalCH/yazap libs/yazap

4. After the previous step is completed, add the following code snippet to your build.zig file:

   exe.addAnonymousModule("yazap", .{
       .source_file = .{ .path = "libs/yazap/src/lib.zig" },
   });

5. You can now import this library in your source file as follows:

   const yazap = @import("yazap");

Documentation

For detailed and comprehensive documentation, please visit this link.

Building and Running Examples

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

Usage

Initializing Yazap

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();

Obtaining the Root Command

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();

Adding Arguments

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",
    }),
});

Adding Subcommands

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);

Parsing Arguments

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;
}

Handling Help

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;
    }
}

Putting it All Together

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;
    }
}

Alternate Parsers

• 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