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 where a and b does not take values.
  • 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.

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, &params, .{ .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, &params, .{});
    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 = &params,
        .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, &params, .{});
    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(), &params);
}


$ 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, &params, .{});
    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(), &params);
}


$ 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