Class CommandLine.Help
- Enclosing class:
- CommandLine
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 ClassesModifier and TypeClassDescriptionstatic enum
Provides methods and inner classes to support using ANSI escape codes in usage help messages.static class
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
(package private) static class
(package private) static class
The DefaultParameterRenderer convertsParameters
to five columns of text to match the default TextTable column layout.(package private) static class
static interface
When customizing online help forOption
details, a customIOptionRenderer
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
When customizing online help forParameters
details, a customIParameterRenderer
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
When customizing online usage help for an option parameter or a positional parameter, a customIParamLabelRenderer
can be used to render the parameter name or label to a String.static class
Use a Layout to format usage help text for options and parameters in tabular format.(package private) static class
The MinimalOptionRenderer convertsOptions
to a single row with two columns of text: an option name and a description.(package private) static class
The MinimalParameterRenderer convertsParameters
to a single row with two columns of text: the parameters label and a description.(package private) static class
Sorts short strings before longer strings.(package private) static class
SortsOption
instances by their max arity first, then their min arity, then delegates to super class.(package private) static class
SortsOption
instances by their name in case-insensitive alphabetic order.static class
Responsible for spacing outCommandLine.Help.Ansi.Text
values according to theCommandLine.Help.Column
definitions the table was created with. -
Field Summary
FieldsModifier and TypeFieldDescriptionIftrue
, the synopsis line(s) will show an abbreviated synopsis without detailed option names.(package private) final CommandLine.Help.ColorScheme
private final Object
Optional heading preceding the subcommand list.The String to use as the program name in the synopsis line of the help message.private final Map<String,
CommandLine.Help> String[]
Optional custom synopsis lines to use instead of the auto-generated synopsis.protected static final String
Constant String holding the default program name: "<main class>"protected static final String
Constant String holding the default string that separates options from option parameters: "="String[]
Optional text lines to use as the description of the help message, displayed between the synopsis and the options list.Optional heading preceding the description section.String[]
Optional footer text lines displayed at the bottom of the help message.Optional heading preceding the footer section.String[]
Optional header lines displayed at the top of the help message.Optional heading preceding the header section.Immutable list of fields annotated withCommandLine.Option
, in declaration order.Optional heading preceding the options list.private static final int
Option and positional parameter value label renderer used for the synopsis line(s) and the option list.Optional heading preceding the parameter list.Immutable list of fields annotated withCommandLine.Parameters
, or an empty list if no such field exists.Character used to prefix required options in the options list.The String to use as the separator between options and option parameters.Iftrue
, the options list will show default values for all options except booleans.Iftrue
, the options list is sorted alphabetically.Optional heading preceding the synopsis.private static final int
-
Constructor Summary
ConstructorsConstructorDescriptionConstructs a newHelp
instance with a default color scheme, initialized from annotatations on the specified class and superclasses.Help
(Object command, CommandLine.Help.Ansi ansi) Constructs a newHelp
instance with a default color scheme, initialized from annotatations on the specified class and superclasses.Help
(Object command, CommandLine.Help.ColorScheme colorScheme) Constructs a newHelp
instance with the specified color scheme, initialized from annotatations on the specified class and superclasses. -
Method Summary
Modifier and TypeMethodDescriptionGenerates 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).addAllSubcommands
(Map<String, CommandLine> commands) Registers all specified subcommands with this Help.addSubcommand
(String commandName, Object command) Registers the specified subcommand with this Help.ansi()
Returns whether ANSI escape codes are enabled or not.private CommandLine.Help.Ansi.Text
appendOptionSynopsis
(CommandLine.Help.Ansi.Text optionText, Field field, String optionName, String prefix, String suffix) Returns a 2-column list with command names and the first line of their header or (if absent) description.commandListHeading
(Object... params) Returns the text displayed before the command list; an empty string if there are no commands, otherwise the result ofString.format(commandListHeading, params)
.private static int
Returns aLayout
instance configured with the user preferences captured in this Help instance.Returns a new default ParameterRenderer which convertsParameters
to four columns of text to match the default TextTable column layout.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 minimal OptionRenderer which convertsOptions
to a single row with two columns of text: an option name and a description.Returns a new minimal ParameterRenderer which convertsParameters
to a single row with two columns of text: an option name and a description.Returns a value renderer that returns theparamLabel
if defined or the field name otherwise.static Comparator<Field>
Sorts Fields annotated withOption
by their option max arity first, by min arity next, and by option name last.static Comparator<Field>
Sorts Fields annotated withOption
by their option name in case-insensitive alphabetic order.customSynopsis
(Object... params) Returns command custom synopsis as a string.static CommandLine.Help.ColorScheme
Creates and returns a newCommandLine.Help.ColorScheme
initialized with picocli default values: commands are bold, options and parameters use a yellow foreground, and option parameters use italic.description
(Object... params) Returns command description text as a string.descriptionHeading
(Object... params) Returns the text displayed before the description text; an empty string if there is no description, otherwise the result ofString.format(descriptionHeading, params)
.detailedSynopsis
(int synopsisHeadingLength, Comparator<Field> optionSort, boolean clusterBooleanOptions) Generates a detailed synopsis message showing all options and parameters.detailedSynopsis
(Comparator<Field> optionSort, boolean clusterBooleanOptions) Deprecated.Returns command footer text as a string.footerHeading
(Object... params) Returns the text displayed before the footer text; the result ofString.format(footerHeading, params)
.private static String
Returns the command header text as a string.headerHeading
(Object... params) Returns the text displayed before the header text; the result ofString.format(headerHeading, params)
.private static String
heading
(CommandLine.Help.Ansi ansi, String values, Object... params) private static String
static StringBuilder
join
(CommandLine.Help.Ansi ansi, String[] values, StringBuilder sb, Object... params) Formats each of the specified values and appends it to the specified StringBuilder.private static int
maxLength
(Collection<String> any) Returns a description of the options supported by the application.optionList
(CommandLine.Help.Layout layout, Comparator<Field> optionSort, CommandLine.Help.IParamLabelRenderer valueLabelRenderer) Sorts allOptions
with the specifiedcomparator
(if the comparator is non-null
), then adds all non-hidden options to the specified TextTable and returns the result of TextTable.toString().optionListHeading
(Object... params) Returns the text displayed before the option list; an empty string if there are no options, otherwise the result ofString.format(optionListHeading, params)
.Returns the section of the usage help message that lists the parameters with their descriptions.parameterList
(CommandLine.Help.Layout layout, CommandLine.Help.IParamLabelRenderer paramLabelRenderer) Returns the section of the usage help message that lists the parameters with their descriptions.parameterListHeading
(Object... params) Returns the text displayed before the positional parameter list; an empty string if there are no positional parameters, otherwise the result ofString.format(parameterListHeading, params)
.static Comparator<String>
Sorts short strings before longer strings.private static char[]
spaces
(int length) private static String
stringOf
(char chr, int length) synopsis()
Deprecated.usesynopsis(int)
insteadsynopsis
(int synopsisHeadingLength) Returns a synopsis for the command, reserving the specified space for the synopsis heading.synopsisHeading
(Object... params) Returns the text displayed before the synopsis text; the result ofString.format(synopsisHeading, params)
.int
Returns the number of characters the synopsis heading will take on the same line as the synopsis.
-
Field Details
-
DEFAULT_COMMAND_NAME
Constant String holding the default program name: "<main class>"- See Also:
-
DEFAULT_SEPARATOR
Constant String holding the default string that separates options from option parameters: "="- See Also:
-
usageHelpWidth
private static final int usageHelpWidth- See Also:
-
optionsColumnWidth
private static final int optionsColumnWidth- See Also:
-
command
-
commands
-
colorScheme
-
optionFields
Immutable list of fields annotated withCommandLine.Option
, in declaration order. -
positionalParametersFields
Immutable list of fields annotated withCommandLine.Parameters
, or an empty list if no such field exists. -
separator
The String to use as the separator between options and option parameters."="
by default, initialized fromCommandLine.Command.separator()
if defined.- See Also:
-
commandName
The String to use as the program name in the synopsis line of the help message.DEFAULT_COMMAND_NAME
by default, initialized fromCommandLine.Command.name()
if defined. -
description
Optional text lines to use as the description of the help message, displayed between the synopsis and the options list. Initialized fromCommandLine.Command.description()
if theCommand
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
Optional custom synopsis lines to use instead of the auto-generated synopsis. Initialized fromCommandLine.Command.customSynopsis()
if theCommand
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
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 fromCommandLine.Command.header()
if theCommand
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. -
parameterLabelRenderer
Option and positional parameter value label renderer used for the synopsis line(s) and the option list. By default initialized to the result ofcreateDefaultParamLabelRenderer()
, which takes a snapshot of theseparator
at construction time. If the separator is modified after Help construction, you may need to re-initialize this field by callingcreateDefaultParamLabelRenderer()
again. -
abbreviateSynopsis
Iftrue
, the synopsis line(s) will show an abbreviated synopsis without detailed option names. -
sortOptions
Iftrue
, the options list is sorted alphabetically. -
showDefaultValues
Iftrue
, the options list will show default values for all options except booleans. -
requiredOptionMarker
Character used to prefix required options in the options list. -
headerHeading
Optional heading preceding the header section. Initialized fromCommandLine.Command.headerHeading()
, or null. -
synopsisHeading
Optional heading preceding the synopsis. Initialized fromCommandLine.Command.synopsisHeading()
,"Usage: "
by default. -
descriptionHeading
Optional heading preceding the description section. Initialized fromCommandLine.Command.descriptionHeading()
, or null. -
parameterListHeading
Optional heading preceding the parameter list. Initialized fromCommandLine.Command.parameterListHeading()
, or null. -
optionListHeading
Optional heading preceding the options list. Initialized fromCommandLine.Command.optionListHeading()
, or null. -
commandListHeading
Optional heading preceding the subcommand list. Initialized fromCommandLine.Command.commandListHeading()
."Commands:%n"
by default.
-
-
Constructor Details
-
Help
Constructs a newHelp
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
Constructs a newHelp
instance with a default color scheme, initialized from annotatations on the specified class and superclasses.- Parameters:
command
- the annotated object to create usage help foransi
- whether to emit ANSI escape codes or not
-
Help
Constructs a newHelp
instance with the specified color scheme, initialized from annotatations on the specified class and superclasses.- Parameters:
command
- the annotated object to create usage help forcolorScheme
- the color scheme to use
-
-
Method Details
-
addAllSubcommands
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:
-
addSubcommand
Registers the specified subcommand with this Help.- Parameters:
commandName
- the name of the subcommand to display in the usage messagecommand
- the annotated object to get more information from- Returns:
- this Help instance (for method chaining)
-
synopsis
Deprecated.usesynopsis(int)
insteadReturns a synopsis for the command without reserving space for the synopsis heading.- Returns:
- a synopsis
- See Also:
-
synopsis
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
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<Field> optionSort, boolean clusterBooleanOptions) Deprecated.usedetailedSynopsis(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 ornull
if options should not be sortedclusterBooleanOptions
-true
if boolean short options should be clustered into a single string- Returns:
- a detailed synopsis
-
detailedSynopsis
public String detailedSynopsis(int synopsisHeadingLength, Comparator<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 lineoptionSort
- comparator to sort options ornull
if options should not be sortedclusterBooleanOptions
-true
if boolean short options should be clustered into a single string- Returns:
- a detailed synopsis
-
appendOptionSynopsis
private CommandLine.Help.Ansi.Text appendOptionSynopsis(CommandLine.Help.Ansi.Text optionText, Field field, String optionName, String prefix, String suffix) -
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:
-
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
public String optionList(CommandLine.Help.Layout layout, Comparator<Field> optionSort, CommandLine.Help.IParamLabelRenderer valueLabelRenderer) Sorts allOptions
with the specifiedcomparator
(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 listoptionSort
- determines in what orderOptions
should be listed. Declared order ifnull
valueLabelRenderer
- used for options with a parameter- Returns:
- the fully formatted option list
-
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 useparamLabelRenderer
- for rendering parameter names- Returns:
- the section of the usage help message that lists the parameters
-
heading
-
spaces
private static char[] spaces(int length) -
countTrailingSpaces
-
join
public static StringBuilder join(CommandLine.Help.Ansi ansi, 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 notvalues
- the values to format and append to the StringBuildersb
- the StringBuilder to collect the formatted stringsparams
- the parameters to pass to the format method when formatting each value- Returns:
- the specified StringBuilder
-
format
-
customSynopsis
Returns command custom synopsis as a string. A custom synopsis can be zero or more lines, and can be specified declaratively with theCommandLine.Command.customSynopsis()
annotation attribute or programmatically by setting the Help instance'scustomSynopsis
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
Returns command description text as a string. Description text can be zero or more lines, and can be specified declaratively with theCommandLine.Command.description()
annotation attribute or programmatically by setting the Help instance'sdescription
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
Returns the command header text as a string. Header text can be zero or more lines, and can be specified declaratively with theCommandLine.Command.header()
annotation attribute or programmatically by setting the Help instance'sheader
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)
-
headerHeading
Returns the text displayed before the header text; the result ofString.format(headerHeading, params)
.- Parameters:
params
- the parameters to use to format the header heading- Returns:
- the formatted header heading
-
synopsisHeading
Returns the text displayed before the synopsis text; the result ofString.format(synopsisHeading, params)
.- Parameters:
params
- the parameters to use to format the synopsis heading- Returns:
- the formatted synopsis heading
-
descriptionHeading
Returns the text displayed before the description text; an empty string if there is no description, otherwise the result ofString.format(descriptionHeading, params)
.- Parameters:
params
- the parameters to use to format the description heading- Returns:
- the formatted description heading
-
parameterListHeading
Returns the text displayed before the positional parameter list; an empty string if there are no positional parameters, otherwise the result ofString.format(parameterListHeading, params)
.- Parameters:
params
- the parameters to use to format the parameter list heading- Returns:
- the formatted parameter list heading
-
optionListHeading
Returns the text displayed before the option list; an empty string if there are no options, otherwise the result ofString.format(optionListHeading, params)
.- Parameters:
params
- the parameters to use to format the option list heading- Returns:
- the formatted option list heading
-
commandListHeading
Returns the text displayed before the command list; an empty string if there are no commands, otherwise the result ofString.format(commandListHeading, params)
.- Parameters:
params
- the parameters to use to format the command list heading- Returns:
- the formatted command list heading
-
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
-
maxLength
-
join
-
stringOf
-
createDefaultLayout
Returns aLayout
instance configured with the user preferences captured in this Help instance.- Returns:
- a Layout
-
createDefaultOptionRenderer
Returns a new default OptionRenderer which convertsOptions
to five columns of text to match the default TextTable column layout. The first row of values looks like this:- the required option marker
- 2-character short option name (or empty string if no short option exists)
- comma separator (only if both short option and long option exist, empty string otherwise)
- comma-separated string with long option name(s)
- 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
Returns a new minimal OptionRenderer which convertsOptions
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
Returns a new default ParameterRenderer which convertsParameters
to four columns of text to match the default TextTable column layout. The first row of values looks like this:- empty string
- empty string
- parameter(s) label as rendered by the
CommandLine.Help.IParamLabelRenderer
- 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
Returns a new minimal ParameterRenderer which convertsParameters
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
Returns a value renderer that returns theparamLabel
if defined or the field name otherwise.- Returns:
- a new minimal ParamLabelRenderer
-
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
Sorts Fields annotated withOption
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
Sorts Fields annotated withOption
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
Sorts short strings before longer strings.- Returns:
- a comparators that sorts short strings before longer strings
-
ansi
Returns whether ANSI escape codes are enabled or not.- Returns:
- whether ANSI escape codes are enabled or not
-
defaultColorScheme
Creates and returns a newCommandLine.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
-
detailedSynopsis(int, Comparator, boolean)
instead.