zopt: low-ceremony command line parsing for Zig

That's a very interesting perspective

My perspective is essentially this: corporate internal tool CLIs are usually terrible, because they're designed with very little care. (LLM CLI design recommendations are also often terrible, because they are trained on terrible inputs.)

What makes them terrible is not mere sloppiness—e.g., using stdout instead of stderr for error reporting—or lack of care for fluency—e.g., failing to support piping to stdin or from stdout to support composable automation—but simple lack of care for design. (I, perhaps unfairly, have in previous comments blamed the incredibly primitive design of Go's flags module for the carelessly poor design of a lot of automation tooling like Docker.)

The command-line interface is the primary thing that the users will see and interact with. While it is undoubtedly true that they care most about the consequences of the command they're running (i.e., what it does,) they will also care about how convenience and intuitive it was to achieve those ends (assuming, of course, they wrote the command-line invocation by hand.)

Thus, for a certain (common, well-circumscribed) class of command-line scripts, there's benefit in properly designing the command-line interface. In these cases, I often first write the usage text by hand as a single multiline string and think through what a user would want to do, how they might go about doing it, what their assumptions and intuitions will be, &c. Then I go and implement that UI.

Of course, what makes makes for a convenient, intuitive tool doesn't necessarily mean that the grammar that the UI presents is readily expressible in, say, EBNF. In fact, it may be the case that the grammar may be unambiguous but may be context-sensitive, and, consequently, resistant to common declarative parsing techniques. Of course, it's also usually the case that an ad hoc, hand-written, imperative parser is not only more than sufficient to handle these grammars, but the resulting code is very easy for someone (i.e., most programmers who are accustomed to reading through imperative code,) to read through and understand.

Also, as a practical matter, programme configuration is usually a (pure?) function of the command-line arguments, environmental variables, and configuration file contents. If a programme is misbehaving, it should be trivial for someone to read through the code to see exactly how these sources interact, especially considering that these interactions may introduce modalities and may have complex prioritisation. (By the way, it would be very nice if command-line interfaces routinely provided some variation of --config-file /dev/null and --ignore-env so that users can safely use them without having to bwrap … --tmpfs ~ --clearenv … or env -i … to get reliable, repeatable state. One of the benefits of auto-canonicalisation is that it can reveal these hidden dependencies in the iterative prototyping enviroment. One auto-canonicalisation format I like to support is where you get the canonical command-line arguments in shell-quoted form with attached shell comments on why they were set—e.g., --dee default # ~/.config/app.conf line 3.)

In fact, I would argue that there are a number of very common patterns that arise in command line interfaces that become incredibly unwieldy to handle in a declarative manner yet nearly trivial to write and read in an imperative style…

Very similar.

I think the switch inside a while loop (which, again, may actually be very similar to what you have created,) is the dominant style for old C programmes. A lot of GNU utilities look like this. A lot of Shell scripts look this way, too (and I have previously made the mistake of using tools like zparseopts which are convenient but quickly become a huge mess.)

Zig's switch and pattern matching are actually quite good, and (comptime-defined) iterators are a surprisingly good fit for the language, so we can do this (many details elided):

const Map = StaticStringMap(...);
const map: Map = .initComptime(...);

const ArgsIter = ArgsIterator(...);
var args_iter: ArgsIter = .init(...);

var config: ProgrammeConfig = .{};

while (map.get(args_iter.peek()) orelse .missing) |arg| switch(arg) {
  .f, .flag => {
    config.flag = ...;
    _ = args_iter.next(); // consume
  },
  .g, .gee => {
    _ = args_iter.next(); // consume
    config.gee.src = args_iter.next() orelse ...;
    config.gee.dst = args_iter.next() orelse ...; // e.g., like `bwrap --ro-bind src dst`
  },
  .@"--" => break,
  .missing => ...,
};

When trying to write some command-line tooling recently, I found that I became very picky about certain capabilities, based on irritations I faced in very useful but unfortunately designed (yet common) tools like ssh, rsync, socat, qemu, &c.

The ArgsIterator gives you a non-owning, non-allocating iterator over some []const []const u8 transformed into something like a union(enum) { long: []const u8, short: []const u8, ...} that lets you split conjoined -abc → -a, -b, -c options and pattern match against how the pattern-matched switch target was discovered (so, e.g., you can distinguish -f from --f while pattern matching against just the "f" part turned into an enum { f, ... })

This (and your library) are definitely huge improvements over scattered std.mem.eql(u8, ..., ...) (as I've seen a few times in Zig projects,) but I think using a StaticStringMap to turn these into pattern-matchable enum values is quite slick, especially since I also have some facilities for transforming those enum values into enum values that make nested switches more compact. e.g., if you had a chown/chgrp-like that allows --user UID or --user USERNAME or --group GID or --group GROUPNAME, you would want an outer switch on .u, .user, .g, .group and maybe a terser inner switch on enum { user, group } as well as an inner switch on enum { uid, name }.