Package picocli

Class CommandLine.Model.UsageMessageSpec

  • Enclosing class:
    CommandLine.Model
    public static class CommandLine.Model.UsageMessageSpec
extends Object
    Models the usage help message specification and can be used to customize the usage help message.

    This class provides two ways to customize the usage help message:

    • Change the text of the predefined sections (this may also be done declaratively using the annotations)
    • Add custom sections, or remove or re-order predefined sections

    The pre-defined sections have getters and setters that return a String (or array of Strings). For example: description() and description(String...) or header() and header(String...).

    Changing the section order, or adding custom sections can be accomplished with sectionKeys(List) and sectionMap(Map). This gives complete freedom on how a usage help message section is rendered, but it also means that the section renderer is responsible for all aspects of rendering the section, including layout and emitting ANSI escape codes. The CommandLine.Help.TextTable and CommandLine.Help.Ansi.Text classes, and the CommandLine.Help.Ansi.string(String) and CommandLine.Help.Ansi.text(String) methods may be useful.

    The usage help message is created more or less like this: 

     // CommandLine.usage(...) or CommandLine.getUsageMessage(...)
 Help.ColorScheme colorScheme = Help.defaultColorScheme(Help.Ansi.AUTO);
 Help help = getHelpFactory().create(getCommandSpec(), colorScheme)
 StringBuilder result = new StringBuilder();
 for (String key : getHelpSectionKeys()) {
     IHelpSectionRenderer renderer = getHelpSectionMap().get(key);
     if (renderer != null) { result.append(renderer.render(help)); }
 }
 // return or print result

    Where the default help section map is constructed like this:

    
 // The default section renderers delegate to methods in Help for their implementation
 // (using Java 8 lambda notation for brevity):
 Map<String, IHelpSectionRenderer> sectionMap = new HashMap<>();
 sectionMap.put(SECTION_KEY_HEADER_HEADING,         help -> help.headerHeading());
 sectionMap.put(SECTION_KEY_HEADER,                 help -> help.header());
 sectionMap.put(SECTION_KEY_SYNOPSIS_HEADING,       help -> help.synopsisHeading());      //e.g. Usage:
 sectionMap.put(SECTION_KEY_SYNOPSIS,               help -> help.synopsis(help.synopsisHeadingLength())); //e.g. <cmd> [OPTIONS] <subcmd> [COMMAND-OPTIONS] [ARGUMENTS]
 sectionMap.put(SECTION_KEY_DESCRIPTION_HEADING,    help -> help.descriptionHeading());   //e.g. %nDescription:%n%n
 sectionMap.put(SECTION_KEY_DESCRIPTION,            help -> help.description());          //e.g. {"Converts foos to bars.", "Use options to control conversion mode."}
 sectionMap.put(SECTION_KEY_PARAMETER_LIST_HEADING, help -> help.parameterListHeading()); //e.g. %nPositional parameters:%n%n
 sectionMap.put(SECTION_KEY_PARAMETER_LIST,         help -> help.parameterList());        //e.g. [FILE...] the files to convert
 sectionMap.put(SECTION_KEY_OPTION_LIST_HEADING,    help -> help.optionListHeading());    //e.g. %nOptions:%n%n
 sectionMap.put(SECTION_KEY_OPTION_LIST,            help -> help.optionList());           //e.g. -h, --help   displays this help and exits
 sectionMap.put(SECTION_KEY_COMMAND_LIST_HEADING,   help -> help.commandListHeading());   //e.g. %nCommands:%n%n
 sectionMap.put(SECTION_KEY_COMMAND_LIST,           help -> help.commandList());          //e.g.    add       adds the frup to the frooble
 sectionMap.put(SECTION_KEY_FOOTER_HEADING,         help -> help.footerHeading());
 sectionMap.put(SECTION_KEY_FOOTER,                 help -> help.footer());
    Since:
    3.0