jdx/usage v3.0.0

v3.0.0: Spec metadata expansion and Cobra escaping fix

on GitHub

This release adds several new metadata fields to the usage spec and includes a breaking API change to the Spec struct. The spec parser now supports license, before_help, after_help, before_long_help, and after_long_help -- fields that were documented in the spec reference but silently ignored until now. The Spec struct has been marked #[non_exhaustive] to allow future field additions without further breaking changes.

Breaking Changes

The Spec struct now has the #[non_exhaustive] attribute. If you construct Spec values using struct literal syntax, your code will need to be updated:

// Before (no longer compiles)
let spec = Spec { name: "my-cli".into(), bin: "mycli".into(), /* ... */ };

// After (option 1)
let mut spec = Spec::default();
spec.name = "my-cli".into();
spec.bin = "mycli".into();

// After (option 2)
let spec = Spec { name: "my-cli".into(), bin: "mycli".into(), ..Default::default() };

This change was made so that new fields can be added to Spec in future minor releases without breaking downstream code. (#542 by @jdx, fixes #537)

Added

• Support for license, before_help, after_help, before_long_help, and after_long_help top-level metadata fields in the usage spec. These fields are now parsed, serialized, and included in spec merges and generated docs. For example:

  license "MIT"
  before_help "Welcome to my CLI"
  after_help "See the docs for more info"
  before_long_help "Detailed welcome text"
  after_long_help "Detailed footer text"

  (#542 by @jdx)

• New community integration: Ruby's OptionParser via option_parser_usage. (#533 by @packrat386)

Fixed

• The Cobra integration now correctly escapes newlines (\n), tabs (\t), and carriage returns (\r) in KDL output. Previously, Cobra commands with multi-line help text would produce invalid KDL specs that failed to parse. (#539 by @thecodesmith)

Changed

• Updated the roff dependency from 0.2 to 1.0 for man page generation. (#529)

New Contributors

• @thecodesmith made their first contribution in #539
• @packrat386 made their first contribution in #533

Full Changelog: v2.18.2...v3.0.0