clulz

A work-in-progress command-line utility library for Zig programs.

Provides a semi-declarative, zero-allocation API for building CLI programs.

NOTE: Blocked by comptime bugs in Zig stage 1. Looking for a temporary workaround for compiler crash when multiple args are specified in CommandDescriptors. See this issue.

Tracking the latest Zig release, currently verison 0.9.1

Usage

To simply prompt for a value, prompt can be used, which will attempt to parse user as the specified type, for example:

const answer = try clulz.prompt(u32, "How much wood would a woodchuck chuck if a woodchuck could chuck wood? ");

promptCommand can be used to prompt for input that is mapped to some command, as defined by CommandDescriptors, a bool indicating whether a command was invoked is returned, for example:

_ = try clulz.promptCommand("example> ", .{}, &.{
    clulz.CommandDescriptor{
        .command = "greet",
        .description = "Print a greeting",
        .args = struct { name: []const u8 },
        .proc = greet,
    },
};

fn greet(args: anytype, _: anytype) !void {
    try clulz.println("Hi, {s}!", .{args.name});
}

The user may enter any number of arguments for a specific command, if less arguments are entered than the command proc takes then the user will be prompted for each missing argument:

example> greet   
enter name: Ziggy
Hi, Ziggy!

A builtin help command is derived from the defined CommandDescriptors. See this issue re. allowing the builtin help to be overidden.

See example.zig for a more complete usage example. To run it:

zig run src/example.zig