How to add to the Error context?

[dimo414]

I'd like to add an additional note to an argument that has changed from being optional to required, explaining the change and what callers should do.

I noticed Error.context() and Error.insert() but it's not clear to me how they're intended to be used. In particular, it does not seem like adding context to an error changes the information an error displays on .print() / .exit(). Here's a playground demonstrating what I was trying, namely to call .insert() on the Error returned by .try_parse() before printing the error. Despite inserting additional context the displayed error doesn't change.

I've seen ErrorFormatter as well but the documentation doesn't address whether using error contexts requires custom formatting. In the same vein, the documentation on ContextKind is rather sparse. It describes what the different kinds are, but doesn't detail how they should be used or the effects of doing so.

[epage]

See https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=d0f235722f06cf49c36c7c62816b59d1

At the moment, RichFormatter only supports ContextValue::StyledStrs for suggestions, see

clap/clap_builder/src/error/format.rs

Line 103 in 6a2b3bf

if let Some(ContextValue::StyledStrs(suggestions)) = suggestions {

[dimo414]

Thanks for the fast response! Just to confirm, by "at the moment" you're saying this functionality isn't completed yet and the plan is (at some point) to support additional value types? Does Custom simply not work at present? Suggestion should be sufficient for my purposes, I'm just curious.

[epage]

"At this moment" in terms of that is all clap needs at this time and we can add more on a case-by-case basic. Doing so can increase build times and constrain us on compatibility, so we will step carefully.

Custom doesn't seem to be used at all by us.... I wonder if we should remove that to avoid confusion.

[dimo414]

It would be great if the unsupported options at least triggered some sort of failure, even just debug_assert!() checks if unimplemented!() is too costly. Or maybe documentation clarifications would be sufficient? I appreciate not wanting to implement functionality the library doesn't need, but as-is they look like usable parts of the public API and the failure mode is pretty confusing. Anyways thanks for your help.

[epage]

These are already fairly advanced use cases and we hadn't even intended people to extend the errors like this. Overall, this is a general system that people can extend to their own ends. This is just a limitation of the default formatter and so any documentation would be limited to that which I expect most people won't look at.