How can I construct the help functionality to divide subcommands into groups with separate descriptive headers?

Question

A tool I am currently working on has a lot of subcommands which makes picocli's help output unclear. My code looks like this:

@Command(name = "toolName",
    version = "version",
    sortOptions = false,
    parameterListHeading = "%nParameters:%n",
    optionListHeading = "%nOptions:%n",
    commandListHeading = "%nThese are common commands:%n%n",
    subcommands = {
    command1.class,
    command2.class,
    command3.class,
    etc.class }

With help as:

@Option(names = {"-h", "--help"}, scope = ScopeType.INHERIT, usageHelp = true,
        description = "Display this help message.")
boolean usageHelpRequested;

I want the help output to look similar to git's:

git bash --help output

Here subcommands are divided into different functionalities (like start a working area) with a description. Is this possible using picocli?

score 1 · Accepted Answer · answered Apr 08 '22 at 02:49

Yes that is possible by diving under the hood of picocli's Help API.

One idea is to have a custom IHelpSectionRenderer, see this example: https://github.com/remkop/picocli/blob/main/picocli-examples/src/main/java/picocli/examples/customhelp/GroupingDemo.java

score 1 · Answer 2 · answered Apr 08 '22 at 12:48

I made a custom IHelpSectionRenderer as advised. In case someone is interested:

@Command(name = "help", helpCommand = true)
class Help implements Runnable {
    public static Map<String, String[]> commandGroups;
    static {
        commandGroups = new HashMap<>();
        commandGroups.put("group1", new String[]{
            "function1", "function2", "function3"});
        commandGroups.put("group2", new String[]{
            "function3", "function4", "function5"});
}

@Override
public void run() {
    CommandLine cmd = new CommandLine(new Tool());

    cmd.getHelpSectionMap().remove(SECTION_KEY_COMMAND_LIST_HEADING);
    cmd.getHelpSectionMap().remove(SECTION_KEY_COMMAND_LIST);
    List<String> keys = new ArrayList<>(cmd.getHelpSectionKeys());

    for (String group : commandGroups.keySet()) {
        String headerSection = "SECTION_KEY_" + group + "_HEADING";
        String commandSection = "SECTION_KEY_" + group;
        cmd.getHelpSectionMap().put(headerSection,
                help -> help.createHeading("%n" + group + ":%n"));
        cmd.getHelpSectionMap().put(commandSection,
                new CommandListRenderer(commandGroups.get(group)));
        keys.add(headerSection);
        keys.add(commandSection);
    }

    cmd.setHelpSectionKeys(keys);
    cmd.usage(System.out);

    }
}

class CommandListRenderer implements IHelpSectionRenderer {
    String[] functions;


    public CommandListRenderer(String[] f) {
        functions = f;
    }

    //@Override
    public String render(Help help) {
        CommandSpec spec = help.commandSpec();
        if (spec.subcommands().isEmpty()) { return ""; }

        // prepare layout: two columns
        // the left column overflows, the right column wraps if text is too long
        Help.TextTable textTable = 
        Help.TextTable.forColumns(help.colorScheme(),
            new Help.Column(30, 2, Help.Column.Overflow.SPAN),
            new Help.Column(spec.usageMessage().width() - 30, 2, 
        Help.Column.Overflow.TRUNCATE));

        for (String f : functions) {
            CommandLine subcommand = spec.subcommands().get(f);
            if (subcommand == null) {
                throw new NotFoundException("Function not found: " + f);
            }
            addCommand(subcommand, textTable);
        }
        return textTable.toString();
    }

public void addCommand(CommandLine cmd, Help.TextTable textTable) {
    // create comma-separated list of command name and aliases
    String names = cmd.getCommandSpec().names().toString();
    names = names.substring(1, names.length() - 1); // remove leading '[' and trailing ']'

    // command description is taken from header or description
    String description = description(cmd.getCommandSpec().usageMessage());

    // add a line for this command to the layout
    textTable.addRowValues(names, description);
}

private String description(Model.UsageMessageSpec usageMessage) {
    if (usageMessage.header().length > 0) {
        return usageMessage.header()[0];
    }
    if (usageMessage.description().length > 0) {
        return usageMessage.description()[0];
    }
    return "";
}

}

How can I construct the help functionality to divide subcommands into groups with separate descriptive headers?

2 Answers2