Package picocli

Class CommandLine.Help

  • Enclosing class:
    CommandLine

    public static class CommandLine.Help
    extends Object
    A collection of methods and inner classes that provide fine-grained control over the contents and layout of the usage help message to display to end users when help is requested or invalid input values were specified.

    Class Diagram of the CommandLine.Help API

    Class Diagram of the CommandLine.Help API

    Layered API

    The CommandLine.Command annotation and the CommandLine.Model.UsageMessageSpec programmatic API equivalent provide the easiest way to configure the usage help message. See the Manual for details.

    This Help class provides high-level functions to create sections of the usage help message and headings for these sections. Instead of calling the CommandLine.usage(PrintStream, CommandLine.Help.ColorScheme) method, application authors may want to create a custom usage help message by reorganizing sections in a different order and/or adding custom sections.

    Finally, the Help class contains inner classes and interfaces that can be used to create custom help messages.

    IOptionRenderer and IParameterRenderer

    Renders a field annotated with CommandLine.Option or CommandLine.Parameters to an array of CommandLine.Help.Ansi.Text values. By default, these values are

    • mandatory marker character (if the option/parameter is required)
    • short option name (empty for parameters)
    • comma or empty (empty for parameters)
    • long option names (the parameter label for parameters)
    • description

    Other components rely on this ordering.

    Layout

    Delegates to the renderers to create CommandLine.Help.Ansi.Text values for the annotated fields, and uses a CommandLine.Help.TextTable to display these values in tabular format. Layout is responsible for deciding which values to display where in the table. By default, Layout shows one option or parameter per table row.

    TextTable

    Responsible for spacing out CommandLine.Help.Ansi.Text values according to the CommandLine.Help.Column definitions the table was created with. Columns have a width, indentation, and an overflow policy that decides what to do if a value is longer than the column's width.

    Text

    Encapsulates rich text with styles and colors in a way that other components like CommandLine.Help.TextTable are unaware of the embedded ANSI escape codes.

    • Constructor Detail

      • Help

        public Help​(Object command)
        Constructs a new Help instance with a default color scheme, initialized from annotatations on the specified class and superclasses.
        Parameters:
        command - the annotated object to create usage help for
      • Help

        public Help​(Object command,
                    CommandLine.Help.Ansi ansi)
        Constructs a new Help instance with a default color scheme, initialized from annotatations on the specified class and superclasses.
        Parameters:
        command - the annotated object to create usage help for
        ansi - whether to emit ANSI escape codes or not
      • Help

        public Help​(CommandLine.Model.CommandSpec commandSpec,
                    CommandLine.Help.ColorScheme colorScheme)
        Constructs a new Help instance with the specified color scheme, initialized from annotatations on the specified class and superclasses.
        Parameters:
        commandSpec - the command model to create usage help for
        colorScheme - the color scheme to use
    • Method Detail

      • colorScheme

        public CommandLine.Help.ColorScheme colorScheme()
        Returns the ColorScheme model that this Help was constructed with.
        Since:
        3.0
      • subcommands

        protected Map<String,​CommandLine.Help> subcommands()
        Returns the map of subcommand Help instances for this command Help.
        Since:
        3.9
      • aliases

        protected List<String> aliases()
        Returns the list of aliases for the command in this Help.
        Since:
        3.9
      • addAllSubcommands

        public CommandLine.Help addAllSubcommands​(Map<String,​CommandLine> commands)
        Registers all specified subcommands with this Help.
        Parameters:
        commands - maps the command names to the associated CommandLine object
        Returns:
        this Help instance (for method chaining)
        See Also:
        CommandLine.getSubcommands()
      • addSubcommand

        @Deprecated
        public CommandLine.Help addSubcommand​(String commandName,
                                              Object command)
        Deprecated.
        Registers the specified subcommand with this Help.
        Parameters:
        commandName - the name of the subcommand to display in the usage message
        command - the CommandSpec or @Command annotated object to get more information from
        Returns:
        this Help instance (for method chaining)
      • abbreviatedSynopsis

        public String abbreviatedSynopsis()
        Generates a generic synopsis like <command name> [OPTIONS] [PARAM1 [PARAM2]...], omitting parts that don't apply to the command (e.g., does not show [OPTIONS] if the command has no options).
        Returns:
        a generic synopsis
      • detailedSynopsis

        @Deprecated
        public String detailedSynopsis​(Comparator<CommandLine.Model.OptionSpec> optionSort,
                                       boolean clusterBooleanOptions)
        Generates a detailed synopsis message showing all options and parameters. Follows the unix convention of showing optional options and parameters in square brackets ([ ]).
        Parameters:
        optionSort - comparator to sort options or null if options should not be sorted
        clusterBooleanOptions - true if boolean short options should be clustered into a single string
        Returns:
        a detailed synopsis
      • detailedSynopsis

        public String detailedSynopsis​(int synopsisHeadingLength,
                                       Comparator<CommandLine.Model.OptionSpec> optionSort,
                                       boolean clusterBooleanOptions)
        Generates a detailed synopsis message showing all options and parameters. Follows the unix convention of showing optional options and parameters in square brackets ([ ]).
        Parameters:
        synopsisHeadingLength - the length of the synopsis heading that will be displayed on the same line
        optionSort - comparator to sort options or null if options should not be sorted
        clusterBooleanOptions - true if boolean short options should be clustered into a single string
        Returns:
        a detailed synopsis
        Since:
        3.0
      • createDetailedSynopsisGroupsText

        protected CommandLine.Help.Ansi.Text createDetailedSynopsisGroupsText​(Set<CommandLine.Model.ArgSpec> outparam_groupArgs)
        Returns a Text object containing a partial detailed synopsis showing only the options and positional parameters in the specified validating groups, starting with a " " space.
        Parameters:
        outparam_groupArgs - all options and positional parameters in the groups this method generates a synopsis for; these options and positional parameters should be excluded from appearing elsewhere in the synopsis
        Returns:
        the formatted groups synopsis elements, starting with a " " space, or an empty Text if this command has no validating groups
        Since:
        4.0
      • createDetailedSynopsisOptionsText

        protected CommandLine.Help.Ansi.Text createDetailedSynopsisOptionsText​(Collection<CommandLine.Model.ArgSpec> done,
                                                                               Comparator<CommandLine.Model.OptionSpec> optionSort,
                                                                               boolean clusterBooleanOptions)
        Returns a Text object containing a partial detailed synopsis showing only the options, starting with a " " space. Follows the unix convention of showing optional options and parameters in square brackets ([ ]).
        Parameters:
        done - the list of options and positional parameters for which a synopsis was already generated. Options in this set should be excluded.
        optionSort - comparator to sort options or null if options should not be sorted
        clusterBooleanOptions - true if boolean short options should be clustered into a single string
        Returns:
        the formatted options, starting with a " " space, or an empty Text if this command has no named options
        Since:
        3.9
      • createDetailedSynopsisPositionalsText

        protected CommandLine.Help.Ansi.Text createDetailedSynopsisPositionalsText​(Collection<CommandLine.Model.ArgSpec> done)
        Returns a Text object containing a partial detailed synopsis showing only the positional parameters, starting with a " " space. Follows the unix convention of showing optional options and parameters in square brackets ([ ]).
        Parameters:
        done - the list of options and positional parameters for which a synopsis was already generated. Positional parameters in this set should be excluded.
        Returns:
        the formatted positional parameters, starting with a " " space, or an empty Text if this command has no positional parameters
        Since:
        3.9
      • createDetailedSynopsisCommandText

        protected CommandLine.Help.Ansi.Text createDetailedSynopsisCommandText()
        Returns a Text object containing a partial detailed synopsis showing only the subcommands, starting with a " " space. Follows the unix convention of showing optional elements in square brackets ([ ]).
        Returns:
        this implementation returns " " + CommandLine.Model.UsageMessageSpec.synopsisSubcommandLabel() if this command has subcommands, an empty Text otherwise.
        Since:
        3.9
      • insertSynopsisCommandName

        protected String insertSynopsisCommandName​(int synopsisHeadingLength,
                                                   CommandLine.Help.Ansi.Text optionsAndPositionalsAndCommandsDetails)
        Returns the detailed synopsis text by inserting the command name before the specified text with options and positional parameters details.
        Parameters:
        synopsisHeadingLength - length of the synopsis heading string to be displayed on the same line as the first synopsis line. For example, if the synopsis heading is "Usage: ", this value is 7.
        optionsAndPositionalsAndCommandsDetails - formatted string with options, positional parameters and subcommands. Follows the unix convention of showing optional options and parameters in square brackets ([ ]).
        Returns:
        the detailed synopsis text, in multiple lines if the length exceeds the usage width
      • synopsisHeadingLength

        public int synopsisHeadingLength()
        Returns the number of characters the synopsis heading will take on the same line as the synopsis.
        Returns:
        the number of characters the synopsis heading will take on the same line as the synopsis.
        See Also:
        detailedSynopsis(int, Comparator, boolean)
      • optionList

        public String optionList​(CommandLine.Help.Layout layout,
                                 Comparator<CommandLine.Model.OptionSpec> optionSort,
                                 CommandLine.Help.IParamLabelRenderer valueLabelRenderer)
        Sorts all Options with the specified comparator (if the comparator is non-null), then adds all non-hidden options to the specified TextTable and returns the result of TextTable.toString().
        Parameters:
        layout - responsible for rendering the option list
        valueLabelRenderer - used for options with a parameter
        Returns:
        the fully formatted option list
        Since:
        3.0
      • parameterList

        public String parameterList()
        Returns the section of the usage help message that lists the parameters with their descriptions.
        Returns:
        the section of the usage help message that lists the parameters
      • parameterList

        public String parameterList​(CommandLine.Help.Layout layout,
                                    CommandLine.Help.IParamLabelRenderer paramLabelRenderer)
        Returns the section of the usage help message that lists the parameters with their descriptions.
        Parameters:
        layout - the layout to use
        paramLabelRenderer - for rendering parameter names
        Returns:
        the section of the usage help message that lists the parameters
      • join

        public static StringBuilder join​(CommandLine.Help.Ansi ansi,
                                         int usageHelpWidth,
                                         boolean adjustCJK,
                                         String[] values,
                                         StringBuilder sb,
                                         Object... params)
        Formats each of the specified values and appends it to the specified StringBuilder.
        Parameters:
        ansi - whether the result should contain ANSI escape codes or not
        usageHelpWidth - the width of the usage help message
        adjustCJK - true if wide Chinese, Japanese and Korean characters should be counted as double the size of other characters for line-breaking purposes
        values - the values to format and append to the StringBuilder
        sb - the StringBuilder to collect the formatted strings
        params - the parameters to pass to the format method when formatting each value
        Returns:
        the specified StringBuilder
        Since:
        4.0
      • customSynopsis

        public String customSynopsis​(Object... params)
        Returns command custom synopsis as a string. A custom synopsis can be zero or more lines, and can be specified declaratively with the CommandLine.Command.customSynopsis() annotation attribute or programmatically by setting the Help instance's customSynopsis(java.lang.Object...) field.
        Parameters:
        params - Arguments referenced by the format specifiers in the synopsis strings
        Returns:
        the custom synopsis lines combined into a single String (which may be empty)
      • description

        public String description​(Object... params)
        Returns command description text as a string. Description text can be zero or more lines, and can be specified declaratively with the CommandLine.Command.description() annotation attribute or programmatically by setting the Help instance's description(java.lang.Object...) field.
        Parameters:
        params - Arguments referenced by the format specifiers in the description strings
        Returns:
        the description lines combined into a single String (which may be empty)
      • header

        public String header​(Object... params)
        Returns the command header text as a string. Header text can be zero or more lines, and can be specified declaratively with the CommandLine.Command.header() annotation attribute or programmatically by setting the Help instance's header(java.lang.Object...) field.
        Parameters:
        params - Arguments referenced by the format specifiers in the header strings
        Returns:
        the header lines combined into a single String (which may be empty)
      • footer

        public String footer​(Object... params)
        Returns command footer text as a string. Footer text can be zero or more lines, and can be specified declaratively with the CommandLine.Command.footer() annotation attribute or programmatically by setting the Help instance's footer(java.lang.Object...) field.
        Parameters:
        params - Arguments referenced by the format specifiers in the footer strings
        Returns:
        the footer lines combined into a single String (which may be empty)
      • headerHeading

        public String headerHeading​(Object... params)
        Returns the text displayed before the header text; the result of String.format(headerHeading, params).
        Parameters:
        params - the parameters to use to format the header heading
        Returns:
        the formatted header heading
      • synopsisHeading

        public String synopsisHeading​(Object... params)
        Returns the text displayed before the synopsis text; the result of String.format(synopsisHeading, params).
        Parameters:
        params - the parameters to use to format the synopsis heading
        Returns:
        the formatted synopsis heading
      • descriptionHeading

        public String descriptionHeading​(Object... params)
        Returns the text displayed before the description text; an empty string if there is no description, otherwise the result of String.format(descriptionHeading, params).
        Parameters:
        params - the parameters to use to format the description heading
        Returns:
        the formatted description heading
      • parameterListHeading

        public String parameterListHeading​(Object... params)
        Returns the text displayed before the positional parameter list; an empty string if there are no positional parameters, otherwise the result of String.format(parameterListHeading, params).
        Parameters:
        params - the parameters to use to format the parameter list heading
        Returns:
        the formatted parameter list heading
      • optionListHeading

        public String optionListHeading​(Object... params)
        Returns the text displayed before the option list; an empty string if there are no options, otherwise the result of String.format(optionListHeading, params).
        Parameters:
        params - the parameters to use to format the option list heading
        Returns:
        the formatted option list heading
      • commandListHeading

        public String commandListHeading​(Object... params)
        Returns the text displayed before the command list; an empty string if there are no commands, otherwise the result of String.format(commandListHeading, params).
        Parameters:
        params - the parameters to use to format the command list heading
        Returns:
        the formatted command list heading
      • footerHeading

        public String footerHeading​(Object... params)
        Returns the text displayed before the footer text; the result of String.format(footerHeading, params).
        Parameters:
        params - the parameters to use to format the footer heading
        Returns:
        the formatted footer heading
      • exitCodeListHeading

        public String exitCodeListHeading​(Object... params)
        Returns the text displayed before the exit code list text; the result of String.format(exitCodeHeading, params).
        Parameters:
        params - the parameters to use to format the exit code heading
        Returns:
        the formatted heading of the exit code section of the usage help message
        Since:
        4.0
      • exitCodeList

        public String exitCodeList()
        Returns a 2-column list with exit codes and their description. Descriptions containing "%n" line separators are broken up into multiple lines.
        Returns:
        a usage help section describing the exit codes
        Since:
        4.0
      • commandList

        public String commandList()
        Returns a 2-column list with command names and the first line of their header or (if absent) description.
        Returns:
        a usage help section describing the added commands
      • commandNamesText

        public CommandLine.Help.Ansi.Text commandNamesText​(String separator)
        Returns a Text object containing the command name and all aliases, separated with the specified separator. Command names will use the command style for the color scheme of this Help.
        Since:
        3.9
      • createDefaultLayout

        public CommandLine.Help.Layout createDefaultLayout()
        Returns a Layout instance configured with the user preferences captured in this Help instance.
        Returns:
        a Layout
      • createDefaultOptionRenderer

        public CommandLine.Help.IOptionRenderer createDefaultOptionRenderer()
        Returns a new default OptionRenderer which converts Options to five columns of text to match the default TextTable column layout. The first row of values looks like this:
        1. the required option marker
        2. 2-character short option name (or empty string if no short option exists)
        3. comma separator (only if both short option and long option exist, empty string otherwise)
        4. comma-separated string with long option name(s)
        5. first element of the CommandLine.Model.ArgSpec.description() array

        Following this, there will be one row for each of the remaining elements of the CommandLine.Model.ArgSpec.description() array, and these rows look like {"", "", "", "", option.description()[i]}.

        If configured, this option renderer adds an additional row to display the default field value.

        Returns:
        a new default OptionRenderer
      • createMinimalOptionRenderer

        public static CommandLine.Help.IOptionRenderer createMinimalOptionRenderer()
        Returns a new minimal OptionRenderer which converts Options to a single row with two columns of text: an option name and a description. If multiple names or descriptions exist, the first value is used.
        Returns:
        a new minimal OptionRenderer
      • createMinimalParameterRenderer

        public static CommandLine.Help.IParameterRenderer createMinimalParameterRenderer()
        Returns a new minimal ParameterRenderer which converts positional parameters to a single row with two columns of text: an option name and a description. If multiple descriptions exist, the first value is used.
        Returns:
        a new minimal ParameterRenderer
      • createMinimalParamLabelRenderer

        public static CommandLine.Help.IParamLabelRenderer createMinimalParamLabelRenderer()
        Returns a value renderer that returns the paramLabel if defined or the field name otherwise.
        Returns:
        a new minimal ParamLabelRenderer
      • createDefaultParamLabelRenderer

        public CommandLine.Help.IParamLabelRenderer createDefaultParamLabelRenderer()
        Returns a new default param label renderer that separates option parameters from their option name with the specified separator string, and, unless CommandLine.Model.ArgSpec.hideParamSyntax() is true, surrounds optional parameters with '[' and ']' characters and uses ellipses ("...") to indicate that any number of a parameter are allowed.
        Returns:
        a new default ParamLabelRenderer
      • createShortOptionNameComparator

        public static Comparator<CommandLine.Model.OptionSpec> createShortOptionNameComparator()
        Sorts OptionSpecs by their option name in case-insensitive alphabetic order. If an option has multiple names, the shortest name is used for the sorting. Help options follow non-help options.
        Returns:
        a comparator that sorts OptionSpecs by their option name in case-insensitive alphabetic order
      • shortestFirst

        public static Comparator<String> shortestFirst()
        Sorts short strings before longer strings.
        Returns:
        a comparators that sorts short strings before longer strings
      • ansi

        public CommandLine.Help.Ansi ansi()
        Returns whether ANSI escape codes are enabled or not.
        Returns:
        whether ANSI escape codes are enabled or not
      • defaultColorScheme

        public static CommandLine.Help.ColorScheme defaultColorScheme​(CommandLine.Help.Ansi ansi)
        Creates and returns a new CommandLine.Help.ColorScheme initialized with picocli default values: commands are bold, options and parameters use a yellow foreground, and option parameters use italic.
        Parameters:
        ansi - whether the usage help message should contain ANSI escape codes or not
        Returns:
        a new default color scheme