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.

Sign up for GitHub

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

Jump to bottom

Displaying command alias in help/usage #2104

Open
roxspring opened this issue Sep 2, 2023 · 3 comments · May be fixed by #2105
Open

Displaying command alias in help/usage #2104

roxspring opened this issue Sep 2, 2023 · 3 comments · May be fixed by #2105
Labels
status: help-wanted 🆘 theme: usagehelp An issue or change related to the usage help message type: enhancement ✨

Comments

@roxspring
Copy link

We have two steps that users perform which are conceptually very different, but technically identical. We define each step as a separate command, and so we've implemented these technically identical steps as a single step1 command with a step2 alias. Technically this works well, but it's a little confusing to ask for help for step2 and get shown help apparently for step1.

Given a subcommand with an alias, is it possible to have that alias used in the help/usage?

@Command(name = "sub", aliases = "alias", mixinStandardHelpOptions = true) class Sub {}
@Command(name = "app", subcommands = {Sub.class}) class App {}

StringWriter out = new StringWriter();
CommandLine app = new CommandLine(new App(), new InnerClassFactory(this));
app.setOut(new PrintWriter(out));
ParseResult result = app.parseArgs("alias", "--help");
CommandLine.printHelpIfRequested(result);

final String expected = format("" +
        "Usage: app alias [-hV]%n" +
        "  -h, --help      Show this help message and exit.%n" +
        "  -V, --version   Print version information and exit.%n");
assertEquals(expected, out.toString());

If it's already possible, I'd love to understand what I'm missing.

If not, and it's welcome, then I'm happy to take recommendations how to implement it and submit a PR!
@remkop
Copy link
Owner

remkop commented Sep 2, 2023 •
edited

Hi @roxspring thank you for raising this!

No you haven't overlooked anything, currently the help is the same regardless of which alias was used to invoke it.

Some thoughts:
Without looking at the code (on my phone now, working from memory) one part of the problem is that the parser doesn't keep track of which alias was actually used to trigger the help being displayed.

maincmd help subcmdAlias1
maincmd help subcmdAlias2

maincmd subcmdAlias1 --help
maincmd subcmdAlias2 -h

It may not be easy to build bookkeeping to keep track of this. Such bookkeeping also needs to handle scenarios like nested sub-subcommands and repeatable subcommands.

Secondly, the display part. Currently help is static: it's not designed to change depending on user input (only the error message is, but that isn't part of the usage help message).

There's no parser state available to the logic that constructs the usage help message. I imagine we would have to use a static variable (or something similar) to store the user-specified command name/alias, to make that alias available to the logic that constructs the usage help message. If you can think of a better solution, ideas are welcome!

Finally, the help is designed to be highly customizable. If applications have tests that assert the exact help message, then these tests may break, that's unavoidable.

But other than that, any changes we introduce here should not impact other applications who have customized their help message, those customizations should continue to work as before.

@remkop remkop added type: enhancement ✨ status: help-wanted 🆘 theme: usagehelp An issue or change related to the usage help message labels Sep 2, 2023
@remkop
Copy link
Owner

remkop commented Sep 2, 2023 •
edited

Reading the description for this ticket again it’s clear the alias is for a subcommand. Apologies, I didn’t read carefully.

I edited my previous comment.

@roxspring roxspring linked a pull request Sep 3, 2023 that will close this issue
Open
@roxspring
Copy link
Author

It may not be easy to build bookkeeping to keep track of this. Such bookkeeping also needs to handle scenarios like nested sub-subcommands and repeatable subcommands.

Looking at repeatable subcommands gave me the inspiration for #2105 - arguably a bit hacky so feedback welcome!

@remkop remkop linked a pull request Sep 12, 2023 that will close this issue
[#2104] Usage shows alias used rather than command name #2105
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
status: help-wanted 🆘 theme: usagehelp An issue or change related to the usage help message type: enhancement ✨
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

[#2104] Usage shows alias used rather than command name roxspring/picocli
2 participants
@roxspring @remkop