optargs

Overview ¶

Package optargs provides a collection of CLI parsing utilities in order to aid in the development of command line applications.

POSIX/GNU GetOpt ¶

At the heart of the optargs package is a Go implementation of the GNU glibc versions the getopt(3), getopt_long(3), and getopt_long_only(3) functions.

Leveraging GNU/POSIX conventions as the backend parser option means that the parser has a very large degree of flexibility without restricting application design choices.

For example, POSIX/GNU allows for the following:

• short-only options.
• long-only options.
• long and short options that do not require a value. I.e. it should be possible to pass `--foo` and specify that it never takes a value, and any attempt to pass it a value should be ignored or or result in an error.
• short-options of any character that is a valid `isgraph()` character; with the exception of `-`, `:` and `;`. This means that the following options are valid: -=, -+, -{, -}, -^, -!, -@, etc.
• short-option compaction: `-abc` is the equivalent of `-a -b -c`
• short-option compaction with optional args: `-abarg` is the equivalent of `-a -b arg`
• arguments to short options that begin with `-`: `-a -1` should pass `-1` as an argument to `-a`
• long-arguments that include any `isgraph()` character in the name, this includes allowing `=` in the name of the argument. For example, `--foo=bar=boo` should map `foo=bar` as the Flag, and `boo` as the value to the flag. This potentially also allows for curious long-arg syntax such as: `--command:arg=value`.
• many-to-one flag mappings. For example, the GNU `ls` command supports `--format=<format>` where each possible `<format>` options is also supported by a unique short-option. For example: `--format=across` = `-x`, `--format=commas` = `-m`, `--format=horizontal` = `-x`, `--format=long` = `-l`, etc.
• The GNU `-W` flag which allows short-options to behave like an undefined long-option. E.g. `-W foo` should be interpreted as if `--foo` was passed to the application.
• long-options that may look similar, but behave differently, from short options. E.g. `-c` and `--c` are allowed to behave differently.
• short-option toggles. Because any `isgraph()` character is a valid short option, `-a` and `-A` can be distinct options that toggle the same field via their respective [Flag.Handle] callbacks. The parser processes options left-to-right, so the last occurrence wins naturally. This is required for tools that pull options from the environment and allow CLI overrides — contradictory sequences like `-aAaAa` must be handled correctly, with the final `-a` or `-A` determining the result.
• multiple short-options that perform the same action. Useful for deprecating a short option while still supporting it: both `-s` (deprecated) and `-S` (current) can map to the same [Flag.Handle] callback. The wrapper controls which options appear in `--help` output, so deprecated aliases can be hidden without removing functionality.
• left-to-right, last-occurrence-wins processing. The iterator yields each option in the order it appears on the command line. When the same option or contradictory options appear multiple times, the handler or application overwrites the value on each encounter. The parser does not accumulate, deduplicate, or reject repeated options — that policy belongs to the handler layer.

It is always possible to implement a Flag handler which imposes opinionated rules atop a non-opinionated parser, but it is not possible to write a less opinionated Flag handler atop an opinionated parser. To that end, the [optarg] parsers do not make any judgements outside of strictly adhering to the POSIX/GNU conventions. Applications are free to implement their own argument handler to best-fit their application's needs.

Flags() ¶

Optargs supports traditional Go style flags which act as convenience methods around GetOpt, GetOptLong, and GetOptLongOnly with the aim of fully supporting drop-in replacements commonly used CLI tooling, such as:

• alexflint/go-args
• spf13/pflag
• spf13/cobra

While these packages are quite useful, they have some fundamental limitations and quirks that come from their design choices which aim to be overcome by optargs and in the case of spf13/pflag, those quirks ultimately percolate up to the user, such as spf13/pflag's boolean flags. Or putting arbitrary restrictions on applications, such as supporting long-only options, but not allowing short-only options. Or not supporting true non-option flags. I.e. many (all?) of the existing Go flag packages only allow an argument to a flag to be optional or required and are not capable of handling flags that never require an argument.