Show/Hide command on specific conditions

[charphi]

The current way to show/hide a command is to set the parameter at compile time.
Similar to IVersionProvider, it could be useful to show/hide a command if certain conditions are met such as platform, OS, resources, ...

[remkop]

Yes, this is currently not easy to achieve. There is an API to customize the help: help section renderers, but for fine-grained changes like you describe it would mean re-implementing large pieces of logic in the Help.listCommands(), Help.listOptions() and Help.listParameters() methods.

One reason this is not easy is that these methods currently query the CommandSpec model directly. What we could do instead is add methods that take a list of the objects to display.

We could change the Help class to something like this:

// CommandLine.Help class

public String commandList() {
    return commandList(subcommands());
}

// NEW method: only specified subcommands are shown
public String commandList(Map<String, Help> subcommands) {
    // logic for creating COMMAND_LIST section of usage help
}

public String optionList() {
    return optionList(commandSpec.options());
}

// NEW method: only specified OptionSpec objects are shown
public String optionList(List<OptionSpec> options) {
    // logic for creating OPTION_LIST section of usage help
}

public String parameterList() {
    return parameterList(commandSpec.positionalParameters());
}

// NEW method: only specified PositionalParamSpec objects are shown
public String parameterList(List<PositionalParamSpec> positionals) {
    // logic for creating PARAMETER_LIST section of usage help
}

This would allow you to customize the usage help message:

IHelpSectionRenderer renderer = (Help help) -> {
    Map<String, Help> subcommands = new LinkedHashMap<>(help.subcommands());
    // remove subcommands that you don't want to show...
    return help.commandList(subcommands);
};
CommandLine cmd= new CommandLine(new MyApp());
cmd.getHelpSectionMap().put(UsageMessageSpec.SECTION_KEY_COMMAND_LIST, renderer);

Requirements like #983 could then be implemented like this:

IHelpSectionRenderer renderer = (Help help) -> {
    // don't show inherited options...
    return help.optionList(help.commandSpec().options().stream()
            .filter(option -> !option.inherited())
            .collect(Collectors.toList()));
};
CommandLine cmd= new CommandLine(new MyApp());
cmd.getHelpSectionMap().put(UsageMessageSpec.SECTION_KEY_OPTION_LIST, renderer);

[remkop]

I pushed a commit to master that should give you the tools to fix this. Specifically, these two new methods:

• Help.allSubcommands
• Help.commandList(Map)

To show all subcommands, including any hidden commands, do this:

IHelpSectionRenderer renderer = (Help help) -> {
    return help.commandList(help.allSubcommands());
};

CommandLine cmd= new CommandLine(new MyApp());
cmd.getHelpSectionMap().put(UsageMessageSpec.SECTION_KEY_COMMAND_LIST, renderer);

Can you try this to see if it meets your requirements?

[charphi]

I've just tested it and it is ok.

Note that I only use help.subcommands() instead of help.allSubcommands() since I consider that an annotated command with hidden parameter set to true should always be hidden.

[remkop]

Great, thanks!

Can you share code for your use case?
I would like to show an example in the release notes of how this feature would be useful.

[remkop]

I’ve added some examples for the different (but similar) use case of hiding inherited options in the usage help message of subcommands:

• CustomOptionListAndSynopsis
• CustomOptionListAndSynopsisWithInheritance

If you have some code you can share that demonstrates your use case, that would be great!

[charphi]

Ok, I will share something as soon as possible.

[charphi]

Here is a simplified example. Is the intent clear enough?

public class Example {

    @Command(name = "myApp")
    static class App {

        @Command(
                name = "do-something",
                description = "Do something useful."
        )
        void doSomething() {
        }

        @Command(
                name = "generate-cmd-launcher",
                description = "Generate a command prompt launcher (${PARENT-COMMAND-NAME}.cmd)."
        )
        void generateCmdLauncher() {
        }
    }

    public static void main(String[] args) {

        IHelpSectionRenderer renderer = (CommandLine.Help help) -> {
            LinkedHashMap<String, Help> map = new LinkedHashMap<>(help.subcommands());
            if (!isWindows()) {
                map.remove("generate-cmd-launcher");
            }
            return help.commandList(map);
        };

        CommandLine cmd = new CommandLine(new App());
        cmd.getHelpSectionMap().put(UsageMessageSpec.SECTION_KEY_COMMAND_LIST, renderer);
        System.out.println(cmd.getUsageMessage());
    }

    static boolean isWindows() {
        return System.getProperty("os.name").toLowerCase().contains("win");
    }
}

[remkop]

Thank you! Very helpful. I added it to the examples.