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)

Examples

StreamingClap

The StreamingClap is base of all the other parsers. It's a streaming parser that uses an args.Iterator to provide it with arguments lazily.

const params = []clap.Param(u8){
    clap.Param(void).flag('h', false, clap.Names.prefix("help")),
    clap.Param(void).option('n', true, clap.Names.prefix("number")),
    clap.Param(void).positional('f'),
};

var os_iter = clap.args.OsIterator.init(allocator);
const iter = &os_iter.iter;
defer os_iter.deinit();

const exe = try iter.next();

var parser = clap.StreamingClap(u8, clap.args.OsIterator.Error).init(params, iter);

while (try parser.next()) |arg| {
    switch (arg.param.id) {
        'h' => debug.warn("Help!\n"),
        'n' => debug.warn("--number = {}\n", arg.value.?),
        '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 params = comptime []clap.Param(void){
    clap.Param(void).flag({}, false, clap.Names.prefix("help")),
    clap.Param(void).option({}, true, clap.Names.prefix("number")),
    clap.Param(void).positional({}),
};

var os_iter = clap.args.OsIterator.init(allocator);
const iter = &os_iter.iter;
defer os_iter.deinit();

const exe = try iter.next();

var args = try clap.ComptimeClap(void, params).parse(allocator, clap.args.OsIterator.Error, 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 params = comptime []clap.Param(void){
    clap.Param(void).init({}, false, clap.Names.prefix("help")),
};

var os_iter = clap.args.OsIterator.init(allocator);
const iter = &os_iter.iter;
defer os_iter.deinit();

const exe = try iter.next();

var args = try clap.ComptimeClap(params).parse(allocator, clap.args.OsIterator.Error, iter);
defer args.deinit();

if (args.flag("--helps"))
    debug.warn("Help!\n");

zig-clap/src/comptime.zig:103:17: error: --helps is not a parameter.
                @compileError(name ++ " is not a parameter.");
                ^
zig-clap/src/comptime.zig:71:45: note: called from here
            const param = comptime findParam(name);
                                            ^
zig-clap/example/comptime-clap.zig:41:18: note: called from here
    if (args.flag("--helps"))
                 ^

Ofc, this limits you to use only parameters that are comptime known.

help

The help and helpEx are functions for printing a simple list of all parameters the program can take.

const stderr_file = try std.io.getStdErr();
var stderr_out_stream = stderr_file.outStream();
const stderr = &stderr_out_stream.stream;

try clap.help(
    stderr,
    []clap.Param([]const u8){
        clap.Param([]const u8).flag(
            "Display this help and exit.",
            clap.Names.prefix("help"),
        ),
        clap.Param([]const u8).flag(
            "Output version information and exit.",
            clap.Names.prefix("version"),
        ),
    },
);

        -h, --help      Display this help and exit.
        -v, --version   Output version information and exit.

The help function is the simplest to call. It only takes an OutStream and a slice of Param([]const u8). This function assumes that the id of each parameter is the help message.

The helpEx is the generic version of help. It can print a help message for any Param, but requires some extra arguments to work.

fn getHelp(_: void, param: clap.Param(u8)) error{}![]const u8 {
    return switch (param.id) {
        'h' => "Display this help and exit.",
        'v' => "Output version information and exit.",
        else => unreachable,
    };
}

fn getValue(_: void, param: clap.Param(u8)) error{}![]const u8 {
    return "";
}

const stderr_file = try std.io.getStdErr();
var stderr_out_stream = stderr_file.outStream();
const stderr = &stderr_out_stream.stream;

try stderr.print("\n");
try clap.helpEx(
    stderr,
    u8,
    []clap.Param(u8){
        clap.Param(u8).flag('h', clap.Names.prefix("help")),
        clap.Param(u8).flag('v', clap.Names.prefix("version")),
    },
    error{},
    {},
    getHelp,
    getValue,
);

        -h, --help      Display this help and exit.
        -v, --version   Output version information and exit.