Mutable app functions are confusing to users and awkward to work with

epage commented 2 years ago

Issue by epage Tuesday Oct 19, 2021 at 15:33 GMT Originally opened as https://github.com/clap-rs/clap/issues/2911

Please complete the following tasks

[X] I have searched the discussions
[X] I have searched the existing issues

Rust Version

rustc 1.55.0 (c8dfcfe04 2021-09-06)

Clap Version

master

Minimal reproducible code

let mut app = ...;
app.render_usage();

Steps to reproduce the bug with the above code

Program with the &mut API

Actual Behaviour

Its awkward and exposing of implementation details. I've seen user confusion akin to "Why does rendering need to modify the app?"

Other uses of this API, like clap_generate, need to use the hidden _build

Expected Behaviour

The types are clean and understandable for a user without ambiguous "modify after build"

Additional Context

I propose we add a struct AppParser that derefs to App.

get_matches will consume App and use _build (only build what is needed for parsing)
App::build(self) -> AppParser will call _build_all
- Contains all of the existing &mut functions, but without the mut

We can implement the additions without breaking behavior; we just add deprecations. Then on the next breaking release, we remove the deprecated behavior.

Debug Output

No response

epage commented 2 years ago

Comment by pksunkara Tuesday Oct 19, 2021 at 19:08 GMT

Same issue as print_*_help and write_*_help methods. I wanted them to be non-mut but couldn't find a way to do it without quickly blowing up the scope of it. IIRC there were some discussions around this when those signatures were implemented which might be useful here.

epage commented 2 years ago

Comment by epage Tuesday Oct 19, 2021 at 19:36 GMT

What are your thoughts on the proposal for solving the mut problem?

IIRC there were some discussions around this when those signatures were implemented which might be useful here.

At least in my initial search, I found https://github.com/clap-rs/clap/pull/540 which didn't have any useful conversation on the subject.

epage commented 2 years ago

Comment by pksunkara Tuesday Oct 19, 2021 at 19:41 GMT

It would be a good approach to explore definitely. Will have to evaluate it properly when we are finalising the design though.

epage commented 2 years ago

Comment by pksunkara Tuesday Oct 19, 2021 at 19:46 GMT

Heh, weird. Couldn't find the discussion now. Maybe it was on something else that was related? 🤷

epage / clapng