From the README:

Derive command line parsers from union and struct types. Provides nested, context aware usage text similar to the zig compiler. Works with existing data structures you may not control.

Features

• field types
  • int, bool, enum, float, optional, array, slice
  • nested unions and structs
• help / usage
  • automatically printed on parsing errors
  • very customizable
  • nested and context aware, showing only one level of help info at once
  • written to parse_options.err_writer (default std.io.null_writer)
  • accessible from any print() method: std.debug.print("{help}", .{parse_result});
• diagnostics which clearly point to parsing errors
• easily dump parse results
  • from any print() method: std.debug.print("{}", .{parse_result});
• derive short names by setting clarp_options.derive_short_names and override them with FieldOption.short
• apply clarp_options to types you don't control with parseWithOptions()
• rename long names with FieldOption.long
• long and short options can be parsed with any of these forms:

  Long	Short
  --foo value	-f value
  --foo=value	-f=value
  --foovalue	-fvalue

Overview

Union types create alternative commands. Commands match field names exactly.

Struct types create sequences of options. Options match field names with leading dashes such as --text_color for field text_color. Named options can be parsed out of order. Unnamed, positional parsing may be enabled by setting clarp_options.fields.<field_name>.positional.

Tuple types create unnamed sequences and are parsed strictly by position.

Bool fields create 'flags' and may be specified as --flag or true/false when unnamed. They are always optional and default to false.

Slice fields require an allocator and consume input until an argument is found which starts with '-' or end of arguments. clarp_options.end_marker may also be used to mark the end of field's arguments. This may be necessary with unnamed, positional fields. An Allocator can be passed as ParseOptions.allocator.

Zig version

This package was developed against zig version 0.12.0-dev.3594+355cceebc

Usage

You can find many examples in the tests.

Add clarp dependency

Fetch

$ zig fetch --save=clarp https://github.com/travisstaloch/clarp/archive/<commit-hash>.tar.gz

This will add the following

// build.zig.zon
.dependencies = .{
    .clarp = .{
        .url = "https://github.com/travisstaloch/clarp/archive/<commit-hash>.tar.gz",
        .hash = ...,
    },
},

Modify build.zig

// build.zig
pub fn build(b: *std.Build) void {
    const clarp = b.dependency("clarp", .{}).module("clarp");
    const exe = b.addExecutable(.{...});
    exe.root_module.addImport("clarp", clarp);
}

Full Example

This program creates a parser and dumps the result to stderr. It is available here and can be run with $ zig build test-demo -- args.

const std = @import("std");
const clarp = @import("clarp");

pub fn main() !void {
    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
    defer arena.deinit();
    const allocator = arena.allocator();

    const ArgParser = clarp.Parser(union(enum) {
        cmd1: struct {
            foo: []const u8,
            pub const clarp_options = clarp.Options(@This()){
                .fields = .{
                    .foo = .{ .desc = "Foo desc." },
                },
            };
        },
        cmd2: struct { enum { a, b } = .a },
        pub const clarp_options = clarp.Options(@This()){
            .fields = .{
                .cmd1 = .{ .desc = "Cmd1 desc.", .short = "c1" },
                .cmd2 = .{ .desc = "Cmd2 desc.", .short = "c2" },
            },
        };
    }, .{});


    const args = try std.process.argsAlloc(allocator);
    const parsed = ArgParser.parse(args, .{
        .err_writer = std.io.getStdErr().writer().any(),
    }) catch |e| switch (e) {
        error.HelpShown => return,
        else => return e,
    };
    std.debug.print("{}\n", .{parsed});
}

clarp_options

When a struct or union contains a pub const clarp_options declaration, it changes parsing behavior. Nested structs and unions may declare their own clarp_options.

ParseOptions

Runtime parsing options. The second argument to clarp.Parser(T).parse().

ParserOptions

Comptime global parsing options. The second argument to clarp.Parser().

help flags

By default, if an arg is help, --help or -h context aware usage is displayed. You may change the help flags by passing an enum type for ParserOptions.help_type.

$ zig-out/bin/testexe help
Usage: testexe [command]

Commands:

  cmd1, c1            Cmd1 description.
  cmd2, c2            Cmd2 description.

General Options:

  help, --help, -h    Print command specific usage.

Notice how this message is derived from the union(enum) passed to clarp.Parser() above and that its clarp_options declaration affects the output, adding the c1 and c2 shorts and descriptions.

Command specific help

$ zig-out/bin/testexe cmd1 help
Usage: testexe cmd1 [options]

  Cmd1 description.

Options:

  --foo: string       Foo description.

General Options:

  help, --help, -h    Print command specific usage.

Command line examples

Here are some results from the ArgParser we defined above in Full Example.

Long names

$ zig-out/bin/testexe cmd1 --foo 'opt1 value'

cmd1: 
  foo: "opt1 value"

Short names

$ zig-out/bin/testexe c1 --foo 'opt1 value'

cmd1: 
  foo: "opt1 value"

$ zig-out/bin/testexe c2 b

cmd2: 
  0: b

Diagnostics

$ zig-out/bin/testexe foo
Usage: testexe [command]

Commands:

  cmd1, c1            Cmd1 description.
  cmd2, c2            Cmd2 description.

General Options:

  help, --help, -h    Print command specific usage.

error at argument 1: foo
                     ^~~
error: UnknownCommand
#... stack trace omitted

River is a dynamic tiling Wayland compositor written in Zig: https://isaacfreund.com/software/river/

Blog post about the River 0.3.0 and Waylock 1.0.0 update: https://isaacfreund.com/blog/river-0.3-waylock-1.0/

From the README:

Tiny and efficient rect packer. The algorithm is very similar to and is heavily inspired by rectpack2D and the blog post it's based on.

From the README:

ziglo is a Zig interface to liblo, an implementation of the Open Sound Control protocol. ziglo provides Zig types for liblo primitives and convenience functions for adding and querying message contents leveraging Zig’s comptime.

From the README:

Explore using a flex/yacc parser from zig to build a json Ast. The resulting json parser is able to parse complex json files such as twitter.json, build a std.json.Value Ast, and print it using std.json.stringify().

From the README:

A slightly cursed library for source-level static instrumentation in Zig.

This repository also includes a simple function-level profiler that outputs to the callgrind format, which is readable by KCacheGrind.

From the README:

This library creates bindings for accessing Javascript from within a WASM runtime

Calling Javascript functions from Zig is a pain. WASM has restrictions on the function API surface, and how references to the runtime environment (Javascript) can be stored. So to access Javascript functionality from Zig, you must create: a function in Zig which is friendly to call, a function export, and a function in Javascript which translates into the call you actually want.

This isn't too bad so far, but the Javascript API surface is large, has a lot of variadic functions, and accepts many types. The result is that your programming loop of just wanting to write code slows down writing a large amount of ill fitting boilerplate whenever you must cross the Zig to Javascript boundary.

This package is clearly inspired by Go's solution to this problem: https://pkg.go.dev/syscall/js

Work-in-progress Python 3.10 Interpreter written in Zig

A time library written in zig, licenced under MIT

Musa is a Wayland compositor with external window managers and first-class multiseat support. Musa is slowly approaching daily usability, but there's still a long way to a polished compositor.

Inspired by River

From the README:

zcrun

a simple linux container runtime built with zig

Features

• namespaces:
  • isolate network, pid, mount, and uts namespace
• cgroups:
  • support cgroups v2
  • limit memory, cpu, or pids (# of procs).
• internet access inside containers using SNAT

Usage

[!NOTE] make sure that ip forwarding is enabled to be able to access the internet inside containers. run sysctl net.ipv4.ip_forward to check if it is enabled. if not, run sudo sysctl -w net.ipv4.ip_forward=1 to enable it.

[!Important] zcrun must be run as root

$ mkdir rootfs
# export container rootfs dir using docker
$ docker export $(docker create busybox) | tar -C rootfs -xvf -
# run the container using zcrun
# zcrun run <name>  <rootfs> <cmd>
$ zcrun run busybox rootfs   sh

Dependencies:

• The iptables command.
• Zig. This branch was tested using version 0.12.0-dev.3191+9cf28d1e9.

From the README:

A gap buffer is like a std.ArrayList, except that rather than having one contiguous block of items, there are two, with a moveable “gap” between them. Although moving the gap requires a copy, insertions and deletions at either side of the gap become O(1) operations.

This repository implements managed, unmanaged and optionally aligned versions of GapBuffer(T). The API is directly inspired by std.ArrayList. The main differences are “Before” and “After” versions of operations that operate or affect the gap—“Before” operations will add or remove elements before the gap. There are also convenience functions for translating a “logical” index into an offset, an element, or a pointer from the buffer, allowing the user to be largely agnostic about the location of the gap.