Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Return help message as String for Command #3873

Closed
2 tasks done
ychiguer opened this issue Jun 27, 2022 · 5 comments · Fixed by #4248
Closed
2 tasks done

Return help message as String for Command #3873

ychiguer opened this issue Jun 27, 2022 · 5 comments · Fixed by #4248
Labels
C-enhancement Category: Raise on the bar on expectations

Comments

@ychiguer
Copy link

Please complete the following tasks

Clap Version

3.1.18

Describe your use case

The only way I could find to use the help message is to print out it to Stdout. In my use case I would like to get the help message as a String as I intend to not print it to Stdout directly.

Describe the solution you'd like

A function that returns the help message as a String.

Alternatives, if applicable

No response

Additional Context

No response

@ychiguer ychiguer added the C-enhancement Category: Raise on the bar on expectations label Jun 27, 2022
@epage
Copy link
Member

epage commented Jun 27, 2022

We do have Command::write_help so its possible to do this today.

The interesting part to me is that for help, we have a write function and for usage/version we have a render function. We should be more consistent but to what is the question

  • only render functions
  • only write functions
  • both

@ychiguer
Copy link
Author

ychiguer commented Jun 28, 2022

Well the question is about render functions and especially rendering help.

We do have Command::write_help so its possible to do this today.

I think this function might work but would require a lot of missing around in my opinion, and for my use case I would like it simply rendered as a String. The thing is, I think there should be a render function for help as well.

@epage
Copy link
Member

epage commented Jun 29, 2022

To be clear, my point about write_help was in response to the Issue stating that the user can't write to an in-memory structure. It is possible. It can still be valid to ask what the API should more generally look like though.

btw a quick example for write_help:

fn main() {
    let mut cmd = clap::Command::new("myprog");

    let mut out: Vec<u8> = Vec::new();
    cmd.write_help(&mut out).expect("failed to write to buffer");
    let out = String::from_utf8(out).expect("help is utf-8");

    dbg!(&out);
}

Beyond a render variant, this requires:

  • Initializing the buffer
  • Converting the buffer to a String

Random thoughts on the proposal to simplify things for people who just want a String:

  • The gap between write and render is small, making this a lower priority for me
  • write reason for existing is more likely an optimization to avoid allocating a medium sized buffer just for someone writing to stdout/stderr. That optimization is unlikely to have a noticeable impact on any application using it.
  • We currently offer more render functions so being at least consistent with that for now seems reasonable
  • We will likely be revisiting all of these API calls when I re-examine colored output in clap 4
    • I try to avoid user churn where we add a function just to remove it afterwards. We do it at times (ArgSetting::MultipleOccurrences -> Arg::multiple_occurrences -> ArgAction::Append) but we didn't predict that. In this case, we have an expected area of investigation that could have a dramatic impact on the API
    • However, the cost is the same for someone using one way vs the other when we come out with that new API. The bigger concern then is if we deprecate a previous API variant but we are unlikely to be doing that here

Thinking through that, I think I am fine with moving forward with this as long as the review churn ends up being low.

@ychiguer ychiguer closed this as completed Jul 1, 2022
@epage
Copy link
Member

epage commented Jul 1, 2022

@ychiguer how come this is closed? The related PR isn't merged yet and generally Issues are closed as completed when their PR is merged and github will do this automatically if you use the right syntax. See https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword

@epage epage reopened this Jul 1, 2022
@ychiguer
Copy link
Author

ychiguer commented Jul 1, 2022

Must have done it by mistake.

epage added a commit to epage/clap that referenced this issue Sep 22, 2022
The writer is less convenient and isn't offering any performance
benefits of avoidign the extra allocations, so let's render instead.

This supersedes clap-rs#3874

Fixes clap-rs#3873
epage added a commit to epage/clap that referenced this issue Sep 22, 2022
The writer is less convenient and isn't offering any performance
benefits of avoidign the extra allocations, so let's render instead.

This supersedes clap-rs#3874

Fixes clap-rs#3873
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-enhancement Category: Raise on the bar on expectations
Projects
None yet
2 participants