jdx/usage v6.6.0

v6.6.0: Scoped flags and implicit clauses

on GitHub

This small release extends the repeatable clause groups introduced in v6.5.0 with per-instance scoped flags and separator-free (implicit) clauses, and completes their integration across the compiled parser, portable KDL, help, completions, and generated documentation.

Added

• Scoped flags and implicit clauses. Clauses can now carry flag nodes that are scoped to a single repeatable instance and reset at each boundary. The separator is now optional: when omitted, a clause with exactly one required, non-variadic positional ends each instance implicitly as soon as that terminal positional is consumed. Scoped flags precede and apply to the next terminal positional, and the parser rejects ambiguous implicit layouts, conflicting flag spellings, duplicate scalar flags within an instance, and trailing scoped flags that never complete an instance. Threaded through the interpreted parser, the compiled argv parser, Rust derive, portable KDL emission, help/completion, usage diff, and the generated Go bindings (#1343, @jdx). Requires min_usage_version "6.6".

  clause "tools" {
    flag "--postinstall <COMMAND>"
    arg "<tool>"
  }

  use --postinstall A a --postinstall B b produces two tools instances: postinstall="A", tool="a" and postinstall="B", tool="b". In Rust derive, omit separator and place the scoped fields on the nested Args type.

Fixed

• Complete implicit clause integration (#1345, @jdx):
  • Command-level relationships (requires, conflicts, etc.) can now target arguments inside typed clauses in the compiled parser, so e.g. --force can require a clause's terminal positional.
  • Portable KDL now emits spec-facing argument names (e.g. TOOL, --postinstall) for clause relationship fields instead of Rust field selectors, keeping reference-parser round-trips valid.
  • Repeated clauses are now rendered as optional groups (wrapped in […]) in compiled help, manpage synopsis, and Markdown, and clause-scoped flags and arguments now appear in generated documentation. Empty clauses no longer fail to render.

Full Changelog: v6.5.0...v6.6.0

💚 Sponsor usage

usage is maintained by @jdx, an open source developer for entire.io, the title sponsor of the jdx.dev open source tools including mise, aube, hk, and more. Work on usage is funded by sponsorships.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider sponsoring at jdx.dev. Every sponsorship helps the project stay independent and moving.