zlap

zlap is a table-driven command-line parser for Zig 0.17. Describe commands as structs and tagged unions, then parse argv into typed values.

Features

• Flags, positionals, short aliases and short clusters
• Enums, repeated values, environment fallbacks and response files
• Nested commands, help, diagnostics and shell completion
• Compile-time JSON command specifications

Add it to a project

From the consumer package:

zig fetch --save git+https://github.com/lumertzg/zlap.git

This records zlap in the consumer's build.zig.zon. Its build.zig then imports the dependency:

const zlap_dep = b.dependency("zlap", .{ .target = target, .optimize = optimize });
exe.root_module.addImport("zlap", zlap_dep.module("zlap"));

This package exports its module with b.addModule. A consuming package obtains it with b.dependency.

Define and parse commands

Command structs hold flags and positionals. A default makes a field optional, while a field without one is required. Field names become kebab-case long flags unless metadata makes them positional. A tagged union field selects a nested command.

Use parseFrom(T, allocator, argv, options) for explicit argv and error handling. Use parse(T, init) in std.process.Init programs to read process arguments and render help or diagnostics. defaults, fill, and updateFrom support in-place parsing and updates.

See basic and nested examples. Build them with:

cd examples && zig build

The basic example reads ZLAP_JOBS when --jobs is absent:

cd examples
ZLAP_JOBS=4 zig build run-basic -- input.txt
ZLAP_JOBS=4 zig build run-basic -- --jobs 2 input.txt

Flags take precedence over environment values.

Ownership

Scalar strings borrow argv or environment storage. parseFrom and fill allocate lists with the supplied allocator, and callers free populated slices with it. updateFrom uses that allocator for replacements. parse allocates lists in init.arena, which owns their storage.

Other API

writeHelp, writeVersion, and renderDiagnostic render output. completionScript and complete support Bash, Zsh, Fish, PowerShell, and Nushell. spec returns a compile-time JSON description of the command tree.

Unknown flags and commands can include a typo suggestion. Suggestions only consider names accepted in the failing command's scope, including aliases and global flags.

Shell completion

Enable .completion = true with parse, then source completionScript(App, shell) output. Completes flags, subcommands, and enum values. Zsh needs compinit, PowerShell needs version 7, and Nushell needs 0.116+.

JSON command specification

spec(App) returns compile-time JSON with command names, help, enum choices, environment bindings, and validation rules. Relationships reference source field names.

Test

zig build test

Real-shell integration tests run against installed Bash, Zsh, Fish, PowerShell, and Nushell runtimes:

python3 tests/completion.py

Missing shells are skipped locally. CI uses --require-all to require all five.