clap v4.1.0 is now out! See the changelog for more details.

What Changed

This is a fairly minor, minor release.

Stablized Occurrences

Typically, your application wants to parse the arguments the same way between these two styles:

$ cargo build --features one,two --features three,four
$ cargo build --features one,two,three,four

However, there are times you need to differentiate between each occurrence of an argument which we now support with ArgMatches::get_occurrences.

For our derive users, support for this is behind the unstable-v5 feature flag as changing Vec<Vec<T>> to mean "group by occurrence" would be a breaking change. We would appreciate ideas and input on #4626 to improve this and other inferred behavior from types in the future.

Special thanks to tmccombs for working on this

Error Message Improvements

Before:

error: Found argument '--optio' which wasn't expected, or isn't valid in this context

  Did you mean '--option'?

Usage: clap-test --option <opt>... [positional] [positional2] [positional3]...

For more information try '--help'

After:

error: unexpected argument '--optio'

  note: argument '--option' exists

Usage: clap-test --option <opt>... [positional] [positional2] [positional3]...

For more information, try '--help'.

clap has not had a style guide and has generally been inconsistent in error messages. While we've worked to make them more consistent, having a stated goal of what we want to be consistent with would help. As an experiment, we've adopted the rustc diagnostic style guide.

Example rustc error:

error[E0425]: cannot find value `arg1` in this scope
    --> src/builder/command.rs:4249:23
     |
4249 |                 arg = arg1.help("Print help");
     |                       ^^^^ help: a local variable with a similar name exists: `arg`

For more information about this error, try `rustc --explain E0425`.
error: could not compile `clap` due to previous error

While changing errors, this gave us an opportunity to do some wordsmithing on the errors to make the problem easier to scan for by

The challenge with succinctness is it can come across as being gruff. When a user gets an error, they are likely frustrated and we need to help defuse things rather than leave them frustrated or make them more frustrated. I'm hoping these messages don't cross over into being gruff but if people have ideas on how to improve them further, we are open to it!

As part of this, we've clarified in our CONTRIBUTING.md what help/error changes constitute a major and minor incompatibility. Help and error output is not meant to be machine readable, so the normal breakage rules do not apply. However, what is a concern is consistency with an application's UI, whether it produces clap-like custom errors or partially overrides some of the output.

What didn't change

As you saw, this does does not contain the most anticipated features, theming and styled user values. Those remain our top priority within the clap project. The error work was more to clear off a branch that has been sitting on my computer for months (waiting a sufficient time for a minor release).

Originally, we had this work planned to immediately follow the clap v4.1 release. One slow down was that I took on maintainership of the toml crate which had many PRs open for years. I felt that I needed to give the toml crate enough attention so I could more easily review and get these languishing changes in. I'll be posting more on this soon.

The toml work extended into some planned family leave that left me with little time for open source work for a couple of months. For what time I did have, I needed to be focused so I could get anything done.

Once the toml work wraps up (hopefully soon), I'll be returning to theming and user styled text for clap.

What you can do to help: