Recent commits to derivepassphrase.git (unstable/cli-parser-state-machine)

Add a test for the new command-line parser's eager option scan step

2026-08-16T22:10:18+02:00

Add a property-based test for the "scan_for_eager_options" step of the
new command-line parser.  This only works for normalized command-lines,
so add additional options and property-based tests for generating parser
states with normalized command-lines.

Some default behaviors of the underlying helper strategies need amending
to generate normalized command-lines by default (or at all).

The strategies for generating general parser states, normalizable
parser states and eager option scanning parser states are very similar
to each other, but still use more copy-and-paste than I would like.
</pre>

Add a test for the new command-line parser normalization step

2026-08-16T18:04:13+02:00

Add a property-based test for the "normalize_options" step of the new
command-line parser.  In particular, add the whole necessary
infrastructure for generating random option, option group and subcommand
objects, random command-lines, and random parser states.

Later stages will likely impose additional constraints on the drawn
objects and command-lines, e.g., that the command-line is normalized, or
that no eager option is included in the subcommand objects.  Such
constraints are already anticipated in the code as well, but the code is
not tested against these contraints, so there are likely still bugs
left.

To further keep the entropy drain low while generating random parser
states, the options, option groups and the subcommand names are
pre-generated into pools of objects/names, and the strategies draw from
those pools.
</pre>

Add the command-line specification under the planned new parser

2026-08-16T16:58:20+02:00

Translate derivepassphrase's existing command-line interface to the
planned new parser infrastructure.

(The new CLI spec is not connected to anything yet.)
</pre>

Add JSON-compatible and usage message-compatible serialization

2026-08-16T16:10:07+02:00

</pre>

Add an option filter for short options and option aliases

2026-08-16T16:09:04+02:00

</pre>

Add parser stages for the planned new command-line argument parser

2026-08-16T16:05:46+02:00

These are the actual parser steps.  They must be run in sequence, and
generally only act on the current "section" of the command-line (up to
the next subcommand boundary).

  - The first step normalizes the command-line, inserting the `--`
    pseudo-option, unclustering clustered options, using canonical
    option and subcommand names, and appending option arguments to the
    argument in `--opt=arg` style.  This step relies on the `canon_map`
    property of CLISubcommand objects.

  - The second step scans for eager options, if necessary replacing the
    whole command-line with the eager option.  This step too relies on
    the `canon_map` property of CLISubcommand objects.

  - The third step locates the subcommand boundary, if any, and returns
    the partial command-line up to that boundary, and a new parser state
    for the remaining section.  This step too relies on the `canon_map`
    property of CLISubcommand objects.

  - An additional "complete" step calls the first three steps, in order,
    on each section of the command-line, and returns the accumulated
    results.  This step relies on the `canon_map` property of
    CLISubcommand objects, indirectly, via the first three steps.
</pre>

Add a canon_map property to the CLISubcommand classes

2026-08-16T15:37:05+02:00

The canonical map of option or subcommand names maps such a name to the
respective option or subcommand object.  It is a dependent attribute
(and thus should be excluded from `__init__`, `__eq__` and `__lt__`,
etc.) and somewhat expensive to compute, so we cache the result in
a global weak key dictionary, because the subcommand objects themselves
are immutable.
</pre>

Add data structures for the planned new command-line argument parser

2026-08-16T15:36:09+02:00

The command-line interface is organized as a hierarchy of "subcommand"
objects, which contain "option group" objects, which contain "option"
objects.  The parser is multi-stage, and has an explicit "state" object
containing the top-level subcommand specification and the command-line
to parse.  The parser steps are monadic, similar to the "Maybe" monad:
each step depends only on the current state, and returns a ParseFailure
or ParseEarlyExit state (which skips any further computation), or
a ParseSuccess state (which does not).

This commit only contains the data structures, not the actual parser
steps.
</pre>

Add new help text messages with option specs and metavars expanded inline

2026-08-16T09:20:06+02:00

For all option one-line descriptions, add variants where the option
specification (as it appears in the help text) is included inline, as
a first line/first paragraph, and the one-line description as the second
paragraph.  In these variants, metavars are expanded inline, as in the
previous commit.

The inline expansion of metavars follows the reasoning from the previous
commit.  The one-line description is due to a planned new command-line
argument parser, which is strictly a parser and thus leaves option
grouping, mutually exclusive options and help text generation to the
application.  Keeping the formatted option specification in the help
text string gives the translators more context, and also allows the
application (the help text formatting part at least) to rediscover the
grouping or mutual exclusivity based on identical help text strings.
</pre>

Add new help and error messages with metavars expanded inline

2026-08-16T08:52:13+02:00

For all texts that aren't one-line option descriptions, add versions of
the text where the metavar is expanded inline, instead of referencing
a different translation string inline.  If multiple texts need to use
the same metavar consistently, pick one of them, and reference that
canonical entry in the other entries' commentary.

This is partly based on search engine/AI feedback on how other projects
solve the problem of wanting to explain mini-formats or other
conventions common to multiple messages to translators: there is no
place to put (machine-readable) references or common explanation, so it
is typical instead to refer inline in the translation commentary to
a canonical entry that contains longer-form explanation instead.  This
is rather awkward to work with if there are multiple layers of expansion
(metavars) in the messages, so it is probably easier on the translators
to include the metavar inline and just note that "canonical text X" uses
the same metavar.  Of course, the canonical text should be short enough
to be easily included inline in the commentary.
</pre>