picocli

Class CommandLine.Help

java.lang.Object

picocli.CommandLine.Help

Enclosing class:

CommandLine

public static class CommandLine.Help
extends java.lang.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.

Layered API

The CommandLine.Command annotation provides the easiest way to customize usage help messages. 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CommandLine.Help.Ansi Provides methods and inner classes to support using ANSI escape codes in usage help messages.
static class	CommandLine.Help.ColorScheme All usage help message are generated with a color scheme that assigns certain styles and colors to common parts of a usage message: the command name, options, positional parameters and option parameters.
static class	CommandLine.Help.Column Columns define the width, indent (leading number of spaces in a column before the value) and Overflow policy of a column in a TextTable.
static interface	CommandLine.Help.IOptionRenderer When customizing online help for Option details, a custom IOptionRenderer can be used to create textual representation of an Option in a tabular format: one or more rows, each containing one or more columns.
static interface	CommandLine.Help.IParameterRenderer When customizing online help for Parameters details, a custom IParameterRenderer can be used to create textual representation of a Parameters field in a tabular format: one or more rows, each containing one or more columns.
static interface	CommandLine.Help.IParamLabelRenderer When customizing online usage help for an option parameter or a positional parameter, a custom IParamLabelRenderer can be used to render the parameter name or label to a String.
static class	CommandLine.Help.Layout Use a Layout to format usage help text for options and parameters in tabular format.
static class	CommandLine.Help.TextTable Responsible for spacing out CommandLine.Help.Ansi.Text values according to the CommandLine.Help.Column definitions the table was created with.

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.Boolean	abbreviateSynopsis If true, the synopsis line(s) will show an abbreviated synopsis without detailed option names.
java.lang.String	commandListHeading Optional heading preceding the subcommand list.
java.lang.String	commandName The String to use as the program name in the synopsis line of the help message.
java.lang.String[]	customSynopsis Optional custom synopsis lines to use instead of the auto-generated synopsis.
protected static java.lang.String	DEFAULT_COMMAND_NAME Constant String holding the default program name: "<main class>"
protected static java.lang.String	DEFAULT_SEPARATOR Constant String holding the default string that separates options from option parameters: "="
java.lang.String[]	description Optional text lines to use as the description of the help message, displayed between the synopsis and the options list.
java.lang.String	descriptionHeading Optional heading preceding the description section.
java.lang.String[]	footer Optional footer text lines displayed at the bottom of the help message.
java.lang.String	footerHeading Optional heading preceding the footer section.
java.lang.String[]	header Optional header lines displayed at the top of the help message.
java.lang.String	headerHeading Optional heading preceding the header section.
java.util.List<java.lang.reflect.Field>	optionFields Immutable list of fields annotated with CommandLine.Option, in declaration order.
java.lang.String	optionListHeading Optional heading preceding the options list.
CommandLine.Help.IParamLabelRenderer	parameterLabelRenderer Option and positional parameter value label renderer used for the synopsis line(s) and the option list.
java.lang.String	parameterListHeading Optional heading preceding the parameter list.
java.util.List<java.lang.reflect.Field>	positionalParametersFields Immutable list of fields annotated with CommandLine.Parameters, or an empty list if no such field exists.
java.lang.Character	requiredOptionMarker Character used to prefix required options in the options list.
java.lang.String	separator The String to use as the separator between options and option parameters.
java.lang.Boolean	showDefaultValues If true, the options list will show default values for all options except booleans.
java.lang.Boolean	sortOptions If true, the options list is sorted alphabetically.
java.lang.String	synopsisHeading Optional heading preceding the synopsis.

Constructor Summary

Constructors

Constructor and Description
CommandLine.Help(java.lang.Object command) Constructs a new Help instance with a default color scheme, initialized from annotatations on the specified class and superclasses.
CommandLine.Help(java.lang.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.
CommandLine.Help(java.lang.Object command, CommandLine.Help.ColorScheme colorScheme) Constructs a new Help instance with the specified color scheme, initialized from annotatations on the specified class and superclasses.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.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).
CommandLine.Help	addAllSubcommands(java.util.Map<java.lang.String,CommandLine> commands) Registers all specified subcommands with this Help.
CommandLine.Help	addSubcommand(java.lang.String commandName, java.lang.Object command) Registers the specified subcommand with this Help.
CommandLine.Help.Ansi	ansi() Returns whether ANSI escape codes are enabled or not.
java.lang.String	commandList() Returns a 2-column list with command names and the first line of their header or (if absent) description.
java.lang.String	commandListHeading(java.lang.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).
CommandLine.Help.Layout	createDefaultLayout() Returns a Layout instance configured with the user preferences captured in this Help instance.
CommandLine.Help.IOptionRenderer	createDefaultOptionRenderer() Returns a new default OptionRenderer which converts Options to five columns of text to match the default TextTable column layout.
CommandLine.Help.IParameterRenderer	createDefaultParameterRenderer() Returns a new default ParameterRenderer which converts Parameters to four columns of text to match the default TextTable column layout.
CommandLine.Help.IParamLabelRenderer	createDefaultParamLabelRenderer() Returns a new default value renderer that separates option parameters from their options with the specified separator string, surrounds optional parameters with '[' and ']' characters and uses ellipses ("...") to indicate that any number of a parameter are allowed.
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.
static CommandLine.Help.IParameterRenderer	createMinimalParameterRenderer() Returns a new minimal ParameterRenderer which converts Parameters to a single row with two columns of text: an option name and a description.
static CommandLine.Help.IParamLabelRenderer	createMinimalParamLabelRenderer() Returns a value renderer that returns the paramLabel if defined or the field name otherwise.
static java.util.Comparator<java.lang.reflect.Field>	createShortOptionArityAndNameComparator() Sorts Fields annotated with Option by their option max arity first, by min arity next, and by option name last.
static java.util.Comparator<java.lang.reflect.Field>	createShortOptionNameComparator() Sorts Fields annotated with Option by their option name in case-insensitive alphabetic order.
java.lang.String	customSynopsis(java.lang.Object... params) Returns command custom synopsis as a string.
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.
java.lang.String	description(java.lang.Object... params) Returns command description text as a string.
java.lang.String	descriptionHeading(java.lang.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).
java.lang.String	detailedSynopsis(java.util.Comparator<java.lang.reflect.Field> optionSort, boolean clusterBooleanOptions) Deprecated. use detailedSynopsis(int, Comparator, boolean) instead.
java.lang.String	detailedSynopsis(int synopsisHeadingLength, java.util.Comparator<java.lang.reflect.Field> optionSort, boolean clusterBooleanOptions) Generates a detailed synopsis message showing all options and parameters.
java.lang.String	footer(java.lang.Object... params) Returns command footer text as a string.
java.lang.String	footerHeading(java.lang.Object... params) Returns the text displayed before the footer text; the result of String.format(footerHeading, params).
java.lang.String	header(java.lang.Object... params) Returns the command header text as a string.
java.lang.String	headerHeading(java.lang.Object... params) Returns the text displayed before the header text; the result of String.format(headerHeading, params).
static java.lang.StringBuilder	join(CommandLine.Help.Ansi ansi, java.lang.String[] values, java.lang.StringBuilder sb, java.lang.Object... params) Formats each of the specified values and appends it to the specified StringBuilder.
java.lang.String	optionList() Returns a description of the options supported by the application.
java.lang.String	optionList(CommandLine.Help.Layout layout, java.util.Comparator<java.lang.reflect.Field> 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().
java.lang.String	optionListHeading(java.lang.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).
java.lang.String	parameterList() Returns the section of the usage help message that lists the parameters with their descriptions.
java.lang.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.
java.lang.String	parameterListHeading(java.lang.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).
static java.util.Comparator<java.lang.String>	shortestFirst() Sorts short strings before longer strings.
java.lang.String	synopsis() Deprecated. use synopsis(int) instead
java.lang.String	synopsis(int synopsisHeadingLength) Returns a synopsis for the command, reserving the specified space for the synopsis heading.
java.lang.String	synopsisHeading(java.lang.Object... params) Returns the text displayed before the synopsis text; the result of String.format(synopsisHeading, params).
int	synopsisHeadingLength() Returns the number of characters the synopsis heading will take on the same line as the synopsis.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_COMMAND_NAME

protected static final java.lang.String DEFAULT_COMMAND_NAME

Constant String holding the default program name: "<main class>"

See Also:

Constant Field Values

DEFAULT_SEPARATOR

protected static final java.lang.String DEFAULT_SEPARATOR

Constant String holding the default string that separates options from option parameters: "="

See Also:

Constant Field Values

optionFields

public final java.util.List<java.lang.reflect.Field> optionFields

Immutable list of fields annotated with CommandLine.Option, in declaration order.

positionalParametersFields

public final java.util.List<java.lang.reflect.Field> positionalParametersFields

Immutable list of fields annotated with CommandLine.Parameters, or an empty list if no such field exists.

separator

public java.lang.String separator

The String to use as the separator between options and option parameters. "=" by default, initialized from CommandLine.Command.separator() if defined.

See Also:

parameterLabelRenderer

commandName

public java.lang.String commandName

The String to use as the program name in the synopsis line of the help message. DEFAULT_COMMAND_NAME by default, initialized from CommandLine.Command.name() if defined.

description

public java.lang.String[] description

Optional text lines to use as the description of the help message, displayed between the synopsis and the options list. Initialized from CommandLine.Command.description() if the Command annotation is present, otherwise this is an empty array and the help message has no description. Applications may programmatically set this field to create a custom help message.

customSynopsis

public java.lang.String[] customSynopsis

Optional custom synopsis lines to use instead of the auto-generated synopsis. Initialized from CommandLine.Command.customSynopsis() if the Command annotation is present, otherwise this is an empty array and the synopsis is generated. Applications may programmatically set this field to create a custom help message.

header

public java.lang.String[] header

Optional header lines displayed at the top of the help message. For subcommands, the first header line is displayed in the list of commands. Values are initialized from CommandLine.Command.header() if the Command annotation is present, otherwise this is an empty array and the help message has no header. Applications may programmatically set this field to create a custom help message.

footer

public java.lang.String[] footer

Optional footer text lines displayed at the bottom of the help message. Initialized from CommandLine.Command.footer() if the Command annotation is present, otherwise this is an empty array and the help message has no footer. Applications may programmatically set this field to create a custom help message.

parameterLabelRenderer

public CommandLine.Help.IParamLabelRenderer parameterLabelRenderer

Option and positional parameter value label renderer used for the synopsis line(s) and the option list. By default initialized to the result of createDefaultParamLabelRenderer(), which takes a snapshot of the separator at construction time. If the separator is modified after Help construction, you may need to re-initialize this field by calling createDefaultParamLabelRenderer() again.

abbreviateSynopsis

public java.lang.Boolean abbreviateSynopsis

If true, the synopsis line(s) will show an abbreviated synopsis without detailed option names.

sortOptions

public java.lang.Boolean sortOptions

If true, the options list is sorted alphabetically.

showDefaultValues

public java.lang.Boolean showDefaultValues

If true, the options list will show default values for all options except booleans.

requiredOptionMarker

public java.lang.Character requiredOptionMarker

Character used to prefix required options in the options list.

headerHeading

public java.lang.String headerHeading

Optional heading preceding the header section. Initialized from CommandLine.Command.headerHeading(), or null.

synopsisHeading

public java.lang.String synopsisHeading

Optional heading preceding the synopsis. Initialized from CommandLine.Command.synopsisHeading(), "Usage: " by default.

descriptionHeading

public java.lang.String descriptionHeading

Optional heading preceding the description section. Initialized from CommandLine.Command.descriptionHeading(), or null.

parameterListHeading

public java.lang.String parameterListHeading

Optional heading preceding the parameter list. Initialized from CommandLine.Command.parameterListHeading(), or null.

optionListHeading

public java.lang.String optionListHeading

Optional heading preceding the options list. Initialized from CommandLine.Command.optionListHeading(), or null.

commandListHeading

public java.lang.String commandListHeading

Optional heading preceding the subcommand list. Initialized from CommandLine.Command.commandListHeading(). "Commands:%n" by default.

footerHeading

public java.lang.String footerHeading

Optional heading preceding the footer section. Initialized from CommandLine.Command.footerHeading(), or null.

Constructor Detail

CommandLine.Help

public CommandLine.Help(java.lang.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

CommandLine.Help

public CommandLine.Help(java.lang.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

CommandLine.Help

public CommandLine.Help(java.lang.Object command,
                CommandLine.Help.ColorScheme colorScheme)

Constructs a new Help instance with the specified color scheme, initialized from annotatations on the specified class and superclasses.

Parameters:

command - the annotated object to create usage help for

colorScheme - the color scheme to use

Method Detail

addAllSubcommands

public CommandLine.Help addAllSubcommands(java.util.Map<java.lang.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

public CommandLine.Help addSubcommand(java.lang.String commandName,
                             java.lang.Object command)

Registers the specified subcommand with this Help.

Parameters:

commandName - the name of the subcommand to display in the usage message

command - the annotated object to get more information from

Returns:

this Help instance (for method chaining)

synopsis

public java.lang.String synopsis()

Deprecated. use synopsis(int) instead

Returns a synopsis for the command without reserving space for the synopsis heading.

Returns:

a synopsis

See Also:

abbreviatedSynopsis(), detailedSynopsis(Comparator, boolean)

synopsis

public java.lang.String synopsis(int synopsisHeadingLength)

Returns a synopsis for the command, reserving the specified space for the synopsis heading.

Parameters:

synopsisHeadingLength - the length of the synopsis heading that will be displayed on the same line

Returns:

a synopsis

See Also:

abbreviatedSynopsis(), detailedSynopsis(Comparator, boolean), synopsisHeading

abbreviatedSynopsis

public java.lang.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

public java.lang.String detailedSynopsis(java.util.Comparator<java.lang.reflect.Field> optionSort,
                                boolean clusterBooleanOptions)

Deprecated. use detailedSynopsis(int, Comparator, boolean) instead.

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 java.lang.String detailedSynopsis(int synopsisHeadingLength,
                                java.util.Comparator<java.lang.reflect.Field> 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

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 java.lang.String optionList()

Returns a description of the options supported by the application. This implementation sorts options alphabetically, and shows only the non-hidden options in a tabular format using the default renderer and default layout.

Returns:

the fully formatted option list

See Also:

optionList(Layout, Comparator, IParamLabelRenderer)

optionList

public java.lang.String optionList(CommandLine.Help.Layout layout,
                          java.util.Comparator<java.lang.reflect.Field> 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

optionSort - determines in what order Options should be listed. Declared order if null

valueLabelRenderer - used for options with a parameter

Returns:

the fully formatted option list

parameterList

public java.lang.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 java.lang.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 java.lang.StringBuilder join(CommandLine.Help.Ansi ansi,
                           java.lang.String[] values,
                           java.lang.StringBuilder sb,
                           java.lang.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

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

customSynopsis

public java.lang.String customSynopsis(java.lang.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 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 java.lang.String description(java.lang.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 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 java.lang.String header(java.lang.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 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 java.lang.String footer(java.lang.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 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 java.lang.String headerHeading(java.lang.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 java.lang.String synopsisHeading(java.lang.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 java.lang.String descriptionHeading(java.lang.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 java.lang.String parameterListHeading(java.lang.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 java.lang.String optionListHeading(java.lang.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 java.lang.String commandListHeading(java.lang.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 java.lang.String footerHeading(java.lang.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

commandList

public java.lang.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

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.Option.description() array

Following this, there will be one row for each of the remaining elements of the CommandLine.Option.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

createDefaultParameterRenderer

public CommandLine.Help.IParameterRenderer createDefaultParameterRenderer()

Returns a new default ParameterRenderer which converts Parameters to four columns of text to match the default TextTable column layout. The first row of values looks like this:

1. empty string
2. empty string
3. parameter(s) label as rendered by the CommandLine.Help.IParamLabelRenderer
4. first element of the CommandLine.Parameters.description() array

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

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

Returns:

a new default ParameterRenderer

createMinimalParameterRenderer

public static CommandLine.Help.IParameterRenderer createMinimalParameterRenderer()

Returns a new minimal ParameterRenderer which converts 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 value renderer that separates option parameters from their options with the specified separator string, 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 java.util.Comparator<java.lang.reflect.Field> createShortOptionNameComparator()

Sorts Fields annotated with Option 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 fields by their option name in case-insensitive alphabetic order

createShortOptionArityAndNameComparator

public static java.util.Comparator<java.lang.reflect.Field> createShortOptionArityAndNameComparator()

Sorts Fields annotated with Option by their option max arity first, by min arity next, and by option name last.

Returns:

a comparator that sorts fields by arity first, then their option name

shortestFirst

public static java.util.Comparator<java.lang.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