public static class CommandLine.Help extends Object
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.
Renders a field annotated with CommandLine.Option
or CommandLine.Parameters
to an array of CommandLine.Help.Ansi.Text
values.
By default, these values are
required
)label
for parameters)Other components rely on this ordering.
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.
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.
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.
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
|
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 positional 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. |
static class |
CommandLine.Help.Visibility
Controls the visibility of certain aspects of the usage help message.
|
Modifier and Type | Field and Description |
---|---|
CommandLine.Model.PositionalParamSpec |
AT_FILE_POSITIONAL_PARAM |
protected static String |
DEFAULT_COMMAND_NAME
Constant String holding the default program name, value defined in
CommandLine.Model.CommandSpec.DEFAULT_COMMAND_NAME . |
protected static String |
DEFAULT_SEPARATOR
Constant String holding the default string that separates options from option parameters, value defined in
CommandLine.Model.ParserSpec.DEFAULT_SEPARATOR . |
CommandLine.Model.OptionSpec |
END_OF_OPTIONS_OPTION |
Constructor and Description |
---|
Help(CommandLine.Model.CommandSpec commandSpec,
CommandLine.Help.ColorScheme colorScheme)
Constructs a new
Help instance with the specified color scheme, initialized from annotations
on the specified class and superclasses. |
Help(Object command)
Constructs a new
Help instance with a default color scheme, initialized from annotations
on the specified class and superclasses. |
Help(Object command,
CommandLine.Help.Ansi ansi)
Constructs a new
Help instance with a default color scheme, initialized from annotations
on the specified class and superclasses. |
Help(Object command,
CommandLine.Help.ColorScheme colorScheme)
Deprecated.
use
picocli.CommandLine.Help#Help(picocli.CommandLine.Model.CommandSpec, picocli.CommandLine.Help.ColorScheme) |
Modifier and Type | Method and Description |
---|---|
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(Map<String,CommandLine> subcommands)
Registers all specified subcommands with this Help.
|
CommandLine.Help |
addSubcommand(String commandName,
Object command)
Deprecated.
use
addAllSubcommands(Map) instead |
protected List<String> |
aliases()
Returns the list of aliases for the command in this Help.
|
Map<String,CommandLine.Help> |
allSubcommands()
Returns the map of all subcommand
Help instances (including hidden commands) for this command Help. |
CommandLine.Help.Ansi |
ansi()
Returns whether ANSI escape codes are enabled or not.
|
String |
atFileParameterList()
Returns the section of the usage help message that lists the @-file and its description.
|
int |
calcLongOptionColumnWidth(List<CommandLine.Model.OptionSpec> options,
List<CommandLine.Model.PositionalParamSpec> positionals,
CommandLine.Help.ColorScheme aColorScheme)
Returns the width of the long options column in the usage help message.
|
CommandLine.Help.ColorScheme |
colorScheme()
Returns the
ColorScheme model that this Help was constructed with. |
String |
commandList()
Returns a 2-column list with the command names and first line of their header or (if absent) description of the commands returned by
subcommands() . |
String |
commandList(Map<String,CommandLine.Help> subcommands)
Returns a 2-column list with the command names and first line of their header or (if absent) description of the specified command map.
|
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) . |
CommandLine.Help.Ansi.Text |
commandNamesText(String separator)
Returns a
Text object containing the command name and all aliases, separated with the specified separator. |
CommandLine.Model.CommandSpec |
commandSpec()
Returns the
CommandSpec model that this Help was constructed with. |
CommandLine.Help.Layout |
createDefaultLayout()
Returns a
Layout instance configured with the user preferences captured in this Help instance. |
CommandLine.Help.Layout |
createDefaultLayout(List<CommandLine.Model.OptionSpec> options,
List<CommandLine.Model.PositionalParamSpec> positionals,
CommandLine.Help.ColorScheme aColorScheme)
Returns a
Layout instance configured with the user preferences captured in this Help instance. |
CommandLine.Help.IOptionRenderer |
createDefaultOptionRenderer()
|
Comparator<CommandLine.Model.OptionSpec> |
createDefaultOptionSort()
Returns a comparator for sorting options, or
null , depending on the settings for this command. |
CommandLine.Help.IParameterRenderer |
createDefaultParameterRenderer()
Returns a new default ParameterRenderer which converts positional parameters to four columns of
text to match the default TextTable column layout.
|
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. |
protected CommandLine.Help.Ansi.Text |
createDetailedSynopsisCommandText()
Returns a Text object containing a partial detailed synopsis showing only the subcommands, starting with a
" " space. |
protected CommandLine.Help.Ansi.Text |
createDetailedSynopsisEndOfOptionsText()
Returns a Text object containing a partial detailed synopsis showing only the end of options delimiter (if enabled), starting with a
" " space. |
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. |
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. |
protected CommandLine.Help.Ansi.Text |
createDetailedSynopsisOptionsText(Collection<CommandLine.Model.ArgSpec> done,
List<CommandLine.Model.OptionSpec> optionList,
Comparator<CommandLine.Model.OptionSpec> optionSort,
boolean clusterBooleanOptions)
Returns a Text object containing a partial detailed synopsis showing only the specified options, starting with a
" " space. |
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. |
String |
createHeading(String text,
Object... params)
Returns a String that can be used as a help section heading.
|
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 positional 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 Comparator<CommandLine.Model.OptionSpec> |
createShortOptionArityAndNameComparator()
|
static Comparator<CommandLine.Model.OptionSpec> |
createShortOptionNameComparator()
Sorts
OptionSpecs by their option name in case-insensitive alphabetic order. |
CommandLine.Help.TextTable |
createTextTable(Map<?,?> map)
Returns a 2-column
TextTable containing data from the specified map:
the keys are put in the left column and the map values are in the right column. |
String |
customSynopsis(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. |
String |
description(Object... params)
Returns command description text as a string.
|
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) . |
String |
detailedSynopsis(Comparator<CommandLine.Model.OptionSpec> optionSort,
boolean clusterBooleanOptions)
Deprecated.
use
detailedSynopsis(int, Comparator, boolean) instead. |
String |
detailedSynopsis(int synopsisHeadingLength,
Comparator<CommandLine.Model.OptionSpec> optionSort,
boolean clusterBooleanOptions)
Generates a detailed synopsis message showing all options and parameters.
|
String |
endOfOptionsList()
Returns the section of the usage help message that lists the
-- End of Options delimiter and its description. |
String |
exitCodeList()
Returns a 2-column list with exit codes and their description.
|
String |
exitCodeListHeading(Object... params)
Returns the text displayed before the exit code list text; the result of
String.format(exitCodeHeading, params) . |
String |
footer(Object... params)
Returns command footer text as a string.
|
String |
footerHeading(Object... params)
Returns the text displayed before the footer text; the result of
String.format(footerHeading, params) . |
String |
fullSynopsis()
Returns the full usage synopsis of this command.
|
boolean |
hasAtFileParameter()
Returns true if the usage help should show the at file parameter in the parameter list, otherwise false.
|
String |
header(Object... params)
Returns the command header text as a string.
|
String |
headerHeading(Object... params)
Returns the text displayed before the header text; the result of
String.format(headerHeading, params) . |
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.
|
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.
|
static StringBuilder |
join(CommandLine.Help.Ansi ansi,
int usageHelpWidth,
String[] values,
StringBuilder sb,
Object... params)
Deprecated.
|
protected String |
makeSynopsisFromParts(int synopsisHeadingLength,
CommandLine.Help.Ansi.Text optionText,
CommandLine.Help.Ansi.Text groupsText,
CommandLine.Help.Ansi.Text endOfOptionsText,
CommandLine.Help.Ansi.Text positionalParamText,
CommandLine.Help.Ansi.Text commandText)
Concatenates the command name and the specified synopsis parts and returns a fully rendered synopsis String.
|
String |
optionList()
Returns a description of all options in this command, including any argument groups.
|
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(). |
String |
optionListExcludingGroups(List<CommandLine.Model.OptionSpec> options)
Returns a description of the specified list of options.
|
String |
optionListExcludingGroups(List<CommandLine.Model.OptionSpec> 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 the specified options to the
specified TextTable and returns the result of TextTable.toString(). |
String |
optionListGroupSections()
Returns a rendered section of the usage help message that contains the argument groups that have a non-
null heading. |
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) . |
List<CommandLine.Model.ArgGroupSpec> |
optionSectionGroups()
Returns the list of
ArgGroupSpec instances in this command that have a non-null heading, most deeply nested argument groups first. |
CommandLine.Help.IParamLabelRenderer |
parameterLabelRenderer()
Option and positional parameter value label renderer used for the synopsis line(s) and the option list.
|
String |
parameterList()
Returns the rendered positional parameters section of the usage help message for all positional parameters in this command.
|
String |
parameterList(CommandLine.Help.Layout layout,
CommandLine.Help.IParamLabelRenderer paramLabelRenderer)
Returns the rendered section of the usage help message that lists all positional parameters in this command with their descriptions.
|
String |
parameterList(List<CommandLine.Model.PositionalParamSpec> positionalParams)
Returns the rendered positional parameters section of the usage help message for the specified positional parameters.
|
String |
parameterList(List<CommandLine.Model.PositionalParamSpec> positionalParams,
CommandLine.Help.Layout layout,
CommandLine.Help.IParamLabelRenderer paramLabelRenderer)
Returns the rendered section of the usage help message that lists the specified parameters with their descriptions.
|
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) . |
static Comparator<String> |
shortestFirst()
Sorts short strings before longer strings.
|
Map<String,CommandLine.Help> |
subcommands()
Returns the map of non-hidden subcommand
Help instances for this command Help. |
String |
synopsis()
Deprecated.
use
synopsis(int) instead |
String |
synopsis(int synopsisHeadingLength)
Returns a synopsis for the command, reserving the specified space for the synopsis heading.
|
String |
synopsisHeading(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.
|
protected static final String DEFAULT_COMMAND_NAME
CommandLine.Model.CommandSpec.DEFAULT_COMMAND_NAME
.protected static final String DEFAULT_SEPARATOR
CommandLine.Model.ParserSpec.DEFAULT_SEPARATOR
.public final CommandLine.Model.PositionalParamSpec AT_FILE_POSITIONAL_PARAM
public final CommandLine.Model.OptionSpec END_OF_OPTIONS_OPTION
public Help(Object command)
Help
instance with a default color scheme, initialized from annotations
on the specified class and superclasses.command
- the annotated object to create usage help forpublic Help(Object command, CommandLine.Help.Ansi ansi)
Help
instance with a default color scheme, initialized from annotations
on the specified class and superclasses.command
- the annotated object to create usage help foransi
- whether to emit ANSI escape codes or not@Deprecated public Help(Object command, CommandLine.Help.ColorScheme colorScheme)
picocli.CommandLine.Help#Help(picocli.CommandLine.Model.CommandSpec, picocli.CommandLine.Help.ColorScheme)
Help
instance with the specified color scheme, initialized from annotations
on the specified class and superclasses.command
- the annotated object to create usage help forcolorScheme
- the color scheme to usepublic Help(CommandLine.Model.CommandSpec commandSpec, CommandLine.Help.ColorScheme colorScheme)
Help
instance with the specified color scheme, initialized from annotations
on the specified class and superclasses.commandSpec
- the command model to create usage help forcolorScheme
- the color scheme to usepublic CommandLine.Model.CommandSpec commandSpec()
CommandSpec
model that this Help was constructed with.public CommandLine.Help.ColorScheme colorScheme()
ColorScheme
model that this Help was constructed with.public Map<String,CommandLine.Help> subcommands()
Help
instances for this command Help.allSubcommands()
public Map<String,CommandLine.Help> allSubcommands()
Help
instances (including hidden commands) for this command Help.subcommands()
protected List<String> aliases()
public CommandLine.Help.IParamLabelRenderer parameterLabelRenderer()
createDefaultParamLabelRenderer()
, which takes a snapshot
of the CommandLine.Model.ParserSpec.separator()
at construction time. If the separator is modified after Help construction, you
may need to re-initialize this field by calling createDefaultParamLabelRenderer()
again.public CommandLine.Help addAllSubcommands(Map<String,CommandLine> subcommands)
subcommands
- the subcommands of this commandsubcommands()
,
allSubcommands()
@Deprecated public CommandLine.Help addSubcommand(String commandName, Object command)
addAllSubcommands(Map)
insteadcommandName
- the name of the subcommand to display in the usage messagecommand
- the CommandSpec
or @Command
annotated object to get more information fromsubcommands()
public String fullSynopsis()
this.synopsisHeading() + this.synopsis(this.synopsisHeadingLength())
@Deprecated public String synopsis()
synopsis(int)
insteadabbreviatedSynopsis()
,
detailedSynopsis(Comparator, boolean)
public String synopsis(int synopsisHeadingLength)
synopsisHeadingLength
- the length of the synopsis heading that will be displayed on the same lineabbreviatedSynopsis()
,
detailedSynopsis(Comparator, boolean)
,
synopsisHeading(java.lang.Object...)
public String abbreviatedSynopsis()
<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).@Deprecated public String detailedSynopsis(Comparator<CommandLine.Model.OptionSpec> optionSort, boolean clusterBooleanOptions)
detailedSynopsis(int, Comparator, boolean)
instead.[ ]
).optionSort
- comparator to sort options or null
if options should not be sortedclusterBooleanOptions
- true
if boolean short options should be clustered into a single stringpublic String detailedSynopsis(int synopsisHeadingLength, Comparator<CommandLine.Model.OptionSpec> optionSort, boolean clusterBooleanOptions)
[ ]
).synopsisHeadingLength
- the length of the synopsis heading that will be displayed on the same lineoptionSort
- comparator to sort options or null
if options should not be sortedclusterBooleanOptions
- true
if boolean short options should be clustered into a single stringprotected String makeSynopsisFromParts(int synopsisHeadingLength, CommandLine.Help.Ansi.Text optionText, CommandLine.Help.Ansi.Text groupsText, CommandLine.Help.Ansi.Text endOfOptionsText, CommandLine.Help.Ansi.Text positionalParamText, CommandLine.Help.Ansi.Text commandText)
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.optionText
- the Ansi.Text object with the rendered options list (excluding the argument groups)groupsText
- the Ansi.Text object showing the rendered argument groupsendOfOptionsText
- the Ansi.Text object containing the end of options delimiter (if enabled)positionalParamText
- the Ansi.Text object showing the rendered positional parameterscommandText
- the Ansi.Text object showing the subcommands part of the synopsisprotected CommandLine.Help.Ansi.Text createDetailedSynopsisGroupsText(Set<CommandLine.Model.ArgSpec> outparam_groupArgs)
" "
space.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" "
space, or an empty Text if this command has no validating groupsprotected CommandLine.Help.Ansi.Text createDetailedSynopsisOptionsText(Collection<CommandLine.Model.ArgSpec> done, Comparator<CommandLine.Model.OptionSpec> optionSort, boolean clusterBooleanOptions)
" "
space.
Follows the unix convention of showing optional options and parameters in square brackets ([ ]
).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 sortedclusterBooleanOptions
- true
if boolean short options should be clustered into a single string" "
space, or an empty Text if this command has no named optionsprotected CommandLine.Help.Ansi.Text createDetailedSynopsisOptionsText(Collection<CommandLine.Model.ArgSpec> done, List<CommandLine.Model.OptionSpec> optionList, Comparator<CommandLine.Model.OptionSpec> optionSort, boolean clusterBooleanOptions)
" "
space.
Follows the unix convention of showing optional options and parameters in square brackets ([ ]
).done
- the list of options and positional parameters for which a synopsis was already generated. Options in this set should be excluded.optionList
- the list of options to include in the synopsisoptionSort
- comparator to sort options or null
if options should not be sortedclusterBooleanOptions
- true
if boolean short options should be clustered into a single string" "
space, or an empty Text if this command has no named optionsprotected CommandLine.Help.Ansi.Text createDetailedSynopsisEndOfOptionsText()
" "
space.
Follows the unix convention of showing optional options and parameters in square brackets ([ ]
)." "
space, or an empty Text if the end of options delimiter should not be shownprotected CommandLine.Help.Ansi.Text createDetailedSynopsisPositionalsText(Collection<CommandLine.Model.ArgSpec> done)
" "
space.
Follows the unix convention of showing optional options and parameters in square brackets ([ ]
).done
- the list of options and positional parameters for which a synopsis was already generated. Positional parameters in this set should be excluded." "
space, or an empty Text if this command has no positional parametersprotected CommandLine.Help.Ansi.Text createDetailedSynopsisCommandText()
" "
space.
Follows the unix convention of showing optional elements in square brackets ([ ]
).CommandLine.Model.UsageMessageSpec.synopsisSubcommandLabel()
if this command has subcommands, an empty Text otherwise.protected String insertSynopsisCommandName(int synopsisHeadingLength, CommandLine.Help.Ansi.Text optionsAndPositionalsAndCommandsDetails)
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 ([ ]
).public int synopsisHeadingLength()
detailedSynopsis(int, Comparator, boolean)
public Comparator<CommandLine.Model.OptionSpec> createDefaultOptionSort()
null
, depending on the settings for this command.null
to indicate that options should not be sorted.public String optionList()
Returns a description of all options in this command, including any argument groups.
This implementation sorts options alphabetically, and shows only the non-hidden options in a tabular format using the default renderer and default layout.
optionListExcludingGroups(List)
,
optionListGroupSections()
public String optionListExcludingGroups(List<CommandLine.Model.OptionSpec> options)
Returns a description of the specified list of options.
This implementation sorts options alphabetically, and shows only the specified options in a tabular format using the default renderer and createDefaultLayout(List, List, ColorScheme) default layout}.
Argument groups are not rendered by this method.
options
- the options to display in the returned rendered section of the usage help messageoptionListExcludingGroups(List, Layout, Comparator, IParamLabelRenderer)
public String optionList(CommandLine.Help.Layout layout, Comparator<CommandLine.Model.OptionSpec> optionSort, CommandLine.Help.IParamLabelRenderer valueLabelRenderer)
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().layout
- the layout responsible for rendering the option listvalueLabelRenderer
- used for options with a parameteroptionListExcludingGroups(List, Layout, Comparator, IParamLabelRenderer)
,
optionListGroupSections()
public String optionListExcludingGroups(List<CommandLine.Model.OptionSpec> optionList, CommandLine.Help.Layout layout, Comparator<CommandLine.Model.OptionSpec> optionSort, CommandLine.Help.IParamLabelRenderer valueLabelRenderer)
Options
with the specified comparator
(if the comparator is non-null
),
then adds the specified options to the
specified TextTable and returns the result of TextTable.toString().
Argument groups are not rendered by this method.optionList
- the options to show (this may be a subset of the options in this command);
it is the responsibility of the caller to remove options that should not be displayedlayout
- the layout responsible for rendering the option listvalueLabelRenderer
- used for options with a parameterpublic String optionListGroupSections()
null
heading.
This is usually shown below the "normal" options of the command (that are not in an argument group).optionList()
,
optionListExcludingGroups(List)
,
optionSectionGroups()
public List<CommandLine.Model.ArgGroupSpec> optionSectionGroups()
ArgGroupSpec
instances in this command that have a non-null
heading, most deeply nested argument groups first.optionListGroupSections()
public String parameterList()
parameterList(List)
public String parameterList(List<CommandLine.Model.PositionalParamSpec> positionalParams)
positionalParams
- the positional parameters to display in the returned rendered section of the usage help message;
the caller is responsible for removing parameters that should not be displayedparameterList(List, Layout, IParamLabelRenderer)
public String parameterList(CommandLine.Help.Layout layout, CommandLine.Help.IParamLabelRenderer paramLabelRenderer)
layout
- the layout to useparamLabelRenderer
- for rendering parameter namespublic String parameterList(List<CommandLine.Model.PositionalParamSpec> positionalParams, CommandLine.Help.Layout layout, CommandLine.Help.IParamLabelRenderer paramLabelRenderer)
positionalParams
- the positional parameters to display in the returned rendered section of the usage help message;
the caller is responsible for removing parameters that should not be displayedlayout
- the layout to useparamLabelRenderer
- for rendering parameter namespublic boolean hasAtFileParameter()
public String atFileParameterList()
public String endOfOptionsList()
--
End of Options delimiter and its description.--
End of Options delimiter and its description.@Deprecated public static StringBuilder join(CommandLine.Help.Ansi ansi, int usageHelpWidth, String[] values, StringBuilder sb, Object... params)
join(Ansi, int, boolean, String[], StringBuilder, Object...)
insteadpublic static StringBuilder join(CommandLine.Help.Ansi ansi, int usageHelpWidth, boolean adjustCJK, String[] values, StringBuilder sb, Object... params)
ansi
- whether the result should contain ANSI escape codes or notusageHelpWidth
- the width of the usage help messageadjustCJK
- true if wide Chinese, Japanese and Korean characters should be counted as double the size of other characters for line-breaking purposesvalues
- 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 valuepublic String customSynopsis(Object... params)
CommandLine.Command.customSynopsis()
annotation attribute or programmatically
by setting the Help instance's customSynopsis(java.lang.Object...)
field.params
- Arguments referenced by the format specifiers in the synopsis stringspublic String description(Object... params)
CommandLine.Command.description()
annotation attribute or programmatically by
setting the Help instance's description(java.lang.Object...)
field.params
- Arguments referenced by the format specifiers in the description stringspublic String header(Object... params)
CommandLine.Command.header()
annotation attribute or programmatically by
setting the Help instance's header(java.lang.Object...)
field.params
- Arguments referenced by the format specifiers in the header stringspublic String footer(Object... params)
CommandLine.Command.footer()
annotation attribute or programmatically by
setting the Help instance's footer(java.lang.Object...)
field.params
- Arguments referenced by the format specifiers in the footer stringspublic String headerHeading(Object... params)
String.format(headerHeading, params)
.params
- the parameters to use to format the header headingpublic String synopsisHeading(Object... params)
String.format(synopsisHeading, params)
.params
- the parameters to use to format the synopsis headingpublic String descriptionHeading(Object... params)
String.format(descriptionHeading, params)
.params
- the parameters to use to format the description headingpublic String parameterListHeading(Object... params)
String.format(parameterListHeading, params)
.params
- the parameters to use to format the parameter list headingpublic String optionListHeading(Object... params)
String.format(optionListHeading, params)
.params
- the parameters to use to format the option list headingpublic String commandListHeading(Object... params)
String.format(commandListHeading, params)
.params
- the parameters to use to format the command list headingpublic String footerHeading(Object... params)
String.format(footerHeading, params)
.params
- the parameters to use to format the footer headingpublic String exitCodeListHeading(Object... params)
String.format(exitCodeHeading, params)
.params
- the parameters to use to format the exit code headingpublic String exitCodeList()
"%n"
line separators are broken up into multiple lines.public String createHeading(String text, Object... params)
%n
format
specifiers will be converted to platform-specific line breaks. Long lines will be wrapped
on word boundaries to ensure they do not exceed the usage message width.
Embedded @|style[,style] ...|@
markup will be converted to Ansi escape codes when
Ansi is enabled, and stripped out otherwise.text
- a printf-style format string that may one or more embedded format specifiersparams
- optional parameters to use when formatting the specified text stringpublic CommandLine.Help.TextTable createTextTable(Map<?,?> map)
TextTable
containing data from the specified map:
the keys are put in the left column and the map values are in the right column.
The width of the left column is the width of the longest key, plus 3 for spacing between the columns.
All map entries are converted to Strings and any embedded %n
format
specifiers are converted to platform-specific line breaks. Long lines are wrapped
on word boundaries to ensure they do not exceed the column width.
Embedded @|style[,style] ...|@
markup will be converted to Ansi escape codes when
Ansi is enabled, and stripped out otherwise.
map
- the map to convert to a TextTable
TextTable
containing data from the specified mappublic String commandList()
subcommands()
.commandList(Map)
public String commandList(Map<String,CommandLine.Help> subcommands)
subcommands()
,
allSubcommands()
public CommandLine.Help.Ansi.Text commandNamesText(String separator)
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.public CommandLine.Help.Layout createDefaultLayout()
Layout
instance configured with the user preferences captured in this Help instance.public CommandLine.Help.Layout createDefaultLayout(List<CommandLine.Model.OptionSpec> options, List<CommandLine.Model.PositionalParamSpec> positionals, CommandLine.Help.ColorScheme aColorScheme)
Layout
instance configured with the user preferences captured in this Help instance.options
- used to calculate the long options column width in the layoutpositionals
- used to calculate the long options column width in the layoutaColorScheme
- used in the layout to create CommandLine.Help.Ansi.Text valuespublic int calcLongOptionColumnWidth(List<CommandLine.Model.OptionSpec> options, List<CommandLine.Model.PositionalParamSpec> positionals, CommandLine.Help.ColorScheme aColorScheme)
options
- the options shown in the usage help messagepositionals
- the positional parameters shown in the usage help messageaColorScheme
- the colorscheme used in the layout to create CommandLine.Help.Ansi.Text valuespublic CommandLine.Help.IOptionRenderer createDefaultOptionRenderer()
Options
to five columns of text to match
the default TextTable column layout. The first row of values looks like this:
CommandLine.Model.ArgSpec.description()
arrayFollowing 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.
public static CommandLine.Help.IOptionRenderer createMinimalOptionRenderer()
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.public CommandLine.Help.IParameterRenderer createDefaultParameterRenderer()
CommandLine.Help.IParamLabelRenderer
CommandLine.Model.ArgSpec.description()
arrayFollowing this, there will be one row for each of the remaining elements of the CommandLine.Model.ArgSpec.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.
public static CommandLine.Help.IParameterRenderer createMinimalParameterRenderer()
public static CommandLine.Help.IParamLabelRenderer createMinimalParamLabelRenderer()
paramLabel
if defined or the field name otherwise.public CommandLine.Help.IParamLabelRenderer createDefaultParamLabelRenderer()
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.public static Comparator<CommandLine.Model.OptionSpec> createShortOptionNameComparator()
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.public static Comparator<CommandLine.Model.OptionSpec> createShortOptionArityAndNameComparator()
public static Comparator<String> shortestFirst()
public CommandLine.Help.Ansi ansi()
public static CommandLine.Help.ColorScheme defaultColorScheme(CommandLine.Help.Ansi ansi)
CommandLine.Help.ColorScheme
initialized with picocli default values: commands are bold,
options and parameters use a yellow foreground, and option parameters use italic.ansi
- whether the usage help message should contain ANSI escape codes or not