clap v4.1.0 is now out! See the changelog for more details.
This is a fairly minor, minor release.
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
For our derive users, support for this is behind the
unstable-v5 feature flag
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
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'
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
- Being more succinct
- Putting the most important details first
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.
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.
toml work wraps up (hopefully soon), I'll be returning to theming
and user styled text for clap.
What you can do to help:
- For theming, we need an API-stable way for users to specifying text styling.
We are preparing the
anstylecrate for this purpose and would appreciate feedback on the API and ANSI style support so we can go as long as possible between breaking changes.
- For user styled text, our plan is to use the most minimal and stable API we can think of, ANSI escape codes. This does mean we need to be able to strip them from output when unsupported which is being tracked in anstyle#5.