public static class CommandLine.Model.UsageMessageSpec
extends java.lang.Object
This class provides two ways to customize the usage help message:
The pre-defined sections have getters and setters that return a String (or array of Strings). For example:
description()
and description(String...)
or header()
and header(String...)
.
Changing the section order, or adding custom sections can be accomplished with sectionKeys(List)
and sectionMap(Map)
.
This gives complete freedom on how a usage help message section is rendered, but it also means that the section renderer
is responsible for all aspects of rendering the section, including layout and emitting ANSI escape codes.
The CommandLine.Help.TextTable
and CommandLine.Help.Ansi.Text
classes, and the CommandLine.Help.Ansi.string(String)
and CommandLine.Help.Ansi.text(String)
methods may be useful.
The usage help message is created more or less like this:
// CommandLine.usage(...) or CommandLine.getUsageMessage(...) Help.ColorScheme colorScheme = Help.defaultColorScheme(Help.Ansi.AUTO); Help help = getHelpFactory().create(getCommandSpec(), colorScheme) StringBuilder result = new StringBuilder(); for (String key : getHelpSectionKeys()) { IHelpSectionRenderer renderer = getHelpSectionMap().get(key); if (renderer != null) { result.append(renderer.render(help)); } } // return or print result
Where the default help section map is constructed like this:
// The default section renderers delegate to methods in Help for their implementation
// (using Java 8 lambda notation for brevity):
Map<String, IHelpSectionRenderer> sectionMap = new HashMap<>();
sectionMap.put(SECTION_KEY_HEADER_HEADING, help -> help.headerHeading());
sectionMap.put(SECTION_KEY_HEADER, help -> help.header());
sectionMap.put(SECTION_KEY_SYNOPSIS_HEADING, help -> help.synopsisHeading()); //e.g. Usage:
sectionMap.put(SECTION_KEY_SYNOPSIS, help -> help.synopsis(help.synopsisHeadingLength())); //e.g. <cmd> [OPTIONS] <subcmd> [COMMAND-OPTIONS] [ARGUMENTS]
sectionMap.put(SECTION_KEY_DESCRIPTION_HEADING, help -> help.descriptionHeading()); //e.g. %nDescription:%n%n
sectionMap.put(SECTION_KEY_DESCRIPTION, help -> help.description()); //e.g. {"Converts foos to bars.", "Use options to control conversion mode."}
sectionMap.put(SECTION_KEY_PARAMETER_LIST_HEADING, help -> help.parameterListHeading()); //e.g. %nPositional parameters:%n%n
sectionMap.put(SECTION_KEY_PARAMETER_LIST, help -> help.parameterList()); //e.g. [FILE...] the files to convert
sectionMap.put(SECTION_KEY_OPTION_LIST_HEADING, help -> help.optionListHeading()); //e.g. %nOptions:%n%n
sectionMap.put(SECTION_KEY_OPTION_LIST, help -> help.optionList()); //e.g. -h, --help displays this help and exits
sectionMap.put(SECTION_KEY_COMMAND_LIST_HEADING, help -> help.commandListHeading()); //e.g. %nCommands:%n%n
sectionMap.put(SECTION_KEY_COMMAND_LIST, help -> help.commandList()); //e.g. add adds the frup to the frooble
sectionMap.put(SECTION_KEY_FOOTER_HEADING, help -> help.footerHeading());
sectionMap.put(SECTION_KEY_FOOTER, help -> help.footer());
Modifier and Type | Field and Description |
---|---|
static int |
DEFAULT_USAGE_WIDTH
Constant holding the default usage message width:
80 . |
static java.lang.String |
SECTION_KEY_COMMAND_LIST
|
static java.lang.String |
SECTION_KEY_COMMAND_LIST_HEADING
|
static java.lang.String |
SECTION_KEY_DESCRIPTION
|
static java.lang.String |
SECTION_KEY_DESCRIPTION_HEADING
|
static java.lang.String |
SECTION_KEY_FOOTER
|
static java.lang.String |
SECTION_KEY_FOOTER_HEADING
|
static java.lang.String |
SECTION_KEY_HEADER
|
static java.lang.String |
SECTION_KEY_HEADER_HEADING
|
static java.lang.String |
SECTION_KEY_OPTION_LIST
|
static java.lang.String |
SECTION_KEY_OPTION_LIST_HEADING
|
static java.lang.String |
SECTION_KEY_PARAMETER_LIST
|
static java.lang.String |
SECTION_KEY_PARAMETER_LIST_HEADING
|
static java.lang.String |
SECTION_KEY_SYNOPSIS
|
static java.lang.String |
SECTION_KEY_SYNOPSIS_HEADING
|
Constructor and Description |
---|
UsageMessageSpec() |
Modifier and Type | Method and Description |
---|---|
boolean |
abbreviateSynopsis()
Returns whether the synopsis line(s) should show an abbreviated synopsis without detailed option names.
|
CommandLine.Model.UsageMessageSpec |
abbreviateSynopsis(boolean newValue)
Sets whether the synopsis line(s) should show an abbreviated synopsis without detailed option names.
|
java.lang.String |
commandListHeading()
Returns the optional heading preceding the subcommand list.
|
CommandLine.Model.UsageMessageSpec |
commandListHeading(java.lang.String newValue)
Sets the optional heading preceding the subcommand list.
|
java.lang.String[] |
customSynopsis()
Returns the optional custom synopsis lines to use instead of the auto-generated synopsis.
|
CommandLine.Model.UsageMessageSpec |
customSynopsis(java.lang.String... customSynopsis)
Sets the optional custom synopsis lines to use instead of the auto-generated synopsis.
|
java.lang.String[] |
description()
Returns the optional text lines to use as the description of the help message, displayed between the synopsis and the
options list.
|
CommandLine.Model.UsageMessageSpec |
description(java.lang.String... description)
Sets the optional text lines to use as the description of the help message, displayed between the synopsis and the
options list.
|
java.lang.String |
descriptionHeading()
Returns the optional heading preceding the description section.
|
CommandLine.Model.UsageMessageSpec |
descriptionHeading(java.lang.String newValue)
Sets the heading preceding the description section.
|
java.lang.String[] |
footer()
Returns the optional footer text lines displayed at the bottom of the help message.
|
CommandLine.Model.UsageMessageSpec |
footer(java.lang.String... footer)
Sets the optional footer text lines displayed at the bottom of the help message.
|
java.lang.String |
footerHeading()
Returns the optional heading preceding the footer section.
|
CommandLine.Model.UsageMessageSpec |
footerHeading(java.lang.String newValue)
Sets the optional heading preceding the footer section.
|
java.lang.String[] |
header()
Returns the optional header lines displayed at the top of the help message.
|
CommandLine.Model.UsageMessageSpec |
header(java.lang.String... header)
Sets the optional header lines displayed at the top of the help message.
|
java.lang.String |
headerHeading()
Returns the optional heading preceding the header section.
|
CommandLine.Model.UsageMessageSpec |
headerHeading(java.lang.String headerHeading)
Sets the heading preceding the header section.
|
CommandLine.IHelpFactory |
helpFactory()
Returns the
IHelpFactory that is used to construct the usage help message. |
CommandLine.Model.UsageMessageSpec |
helpFactory(CommandLine.IHelpFactory helpFactory)
Sets a new
IHelpFactory to customize the usage help message. |
boolean |
hidden()
Returns whether this command should be hidden from the usage help message of the parent command.
|
CommandLine.Model.UsageMessageSpec |
hidden(boolean value)
Set the hidden flag on this command to control whether to show or hide it in the help usage text of the parent command.
|
CommandLine.Model.Messages |
messages()
Returns the Messages for this usage help message specification, or
null . |
CommandLine.Model.UsageMessageSpec |
messages(CommandLine.Model.Messages msgs)
Sets the Messages for this usageMessage specification, and returns this UsageMessageSpec.
|
java.lang.String |
optionListHeading()
Returns the optional heading preceding the options list.
|
CommandLine.Model.UsageMessageSpec |
optionListHeading(java.lang.String newValue)
Sets the heading preceding the options list.
|
java.lang.String |
parameterListHeading()
Returns the optional heading preceding the parameter list.
|
CommandLine.Model.UsageMessageSpec |
parameterListHeading(java.lang.String newValue)
Sets the optional heading preceding the parameter list.
|
char |
requiredOptionMarker()
Returns the character used to prefix required options in the options list.
|
CommandLine.Model.UsageMessageSpec |
requiredOptionMarker(char newValue)
Sets the character used to prefix required options in the options list.
|
java.util.List<java.lang.String> |
sectionKeys()
Returns the section keys in the order that the usage help message should render the sections.
|
CommandLine.Model.UsageMessageSpec |
sectionKeys(java.util.List<java.lang.String> keys)
Sets the section keys in the order that the usage help message should render the sections.
|
java.util.Map<java.lang.String,CommandLine.IHelpSectionRenderer> |
sectionMap()
Returns the map of section keys and renderers used to construct the usage help message.
|
CommandLine.Model.UsageMessageSpec |
sectionMap(java.util.Map<java.lang.String,CommandLine.IHelpSectionRenderer> map)
Sets the map of section keys and renderers used to construct the usage help message to a copy of the specified map.
|
boolean |
showDefaultValues()
Returns whether the options list in the usage help message should show default values for all non-boolean options.
|
CommandLine.Model.UsageMessageSpec |
showDefaultValues(boolean newValue)
Sets whether the options list in the usage help message should show default values for all non-boolean options.
|
boolean |
sortOptions()
Returns whether the options list in the usage help message should be sorted alphabetically.
|
CommandLine.Model.UsageMessageSpec |
sortOptions(boolean newValue)
Sets whether the options list in the usage help message should be sorted alphabetically.
|
java.lang.String |
synopsisHeading()
Returns the optional heading preceding the synopsis.
|
CommandLine.Model.UsageMessageSpec |
synopsisHeading(java.lang.String newValue)
Sets the optional heading preceding the synopsis.
|
int |
width()
Returns the maximum usage help message width.
|
CommandLine.Model.UsageMessageSpec |
width(int newValue)
Sets the maximum usage help message width to the specified value.
|
public static final java.lang.String SECTION_KEY_HEADER_HEADING
CommandLine.Help.headerHeading(Object...)
.public static final java.lang.String SECTION_KEY_HEADER
CommandLine.Help.header(Object...)
.public static final java.lang.String SECTION_KEY_SYNOPSIS_HEADING
CommandLine.Help.synopsisHeading(Object...)
.public static final java.lang.String SECTION_KEY_SYNOPSIS
CommandLine.Help.synopsis(int)
.public static final java.lang.String SECTION_KEY_DESCRIPTION_HEADING
CommandLine.Help.descriptionHeading(Object...)
.public static final java.lang.String SECTION_KEY_DESCRIPTION
CommandLine.Help.description(Object...)
.public static final java.lang.String SECTION_KEY_PARAMETER_LIST_HEADING
CommandLine.Help.parameterListHeading(Object...)
.public static final java.lang.String SECTION_KEY_PARAMETER_LIST
CommandLine.Help.parameterList()
.public static final java.lang.String SECTION_KEY_OPTION_LIST_HEADING
CommandLine.Help.optionListHeading(Object...)
.public static final java.lang.String SECTION_KEY_OPTION_LIST
CommandLine.Help.optionList()
.public static final java.lang.String SECTION_KEY_COMMAND_LIST_HEADING
CommandLine.Help.commandListHeading(Object...)
.public static final java.lang.String SECTION_KEY_COMMAND_LIST
CommandLine.Help.commandList()
.public static final java.lang.String SECTION_KEY_FOOTER_HEADING
CommandLine.Help.footerHeading(Object...)
.public static final java.lang.String SECTION_KEY_FOOTER
CommandLine.Help.footer(Object...)
.public static final int DEFAULT_USAGE_WIDTH
80
.public CommandLine.Model.UsageMessageSpec width(int newValue)
newValue
- the new maximum usage help message width. Must be 55 or greater.UsageMessageSpec
for method chainingjava.lang.IllegalArgumentException
- if the specified width is less than 55public int width()
"picocli.usage.width"
if set, otherwise returns the value set via the width(int)
method, or if not set, the default width.public java.util.List<java.lang.String> sectionKeys()
sectionKeys setter
. The default keys are (in order):
SECTION_KEY_HEADER_HEADING
SECTION_KEY_HEADER
SECTION_KEY_SYNOPSIS_HEADING
SECTION_KEY_SYNOPSIS
SECTION_KEY_DESCRIPTION_HEADING
SECTION_KEY_DESCRIPTION
SECTION_KEY_PARAMETER_LIST_HEADING
SECTION_KEY_PARAMETER_LIST
SECTION_KEY_OPTION_LIST_HEADING
SECTION_KEY_OPTION_LIST
SECTION_KEY_COMMAND_LIST_HEADING
SECTION_KEY_COMMAND_LIST
SECTION_KEY_FOOTER_HEADING
SECTION_KEY_FOOTER
public CommandLine.Model.UsageMessageSpec sectionKeys(java.util.List<java.lang.String> keys)
sectionKeys
public java.util.Map<java.lang.String,CommandLine.IHelpSectionRenderer> sectionMap()
sectionKeys setter
.
Sections that are either not in this map or not in the list returned by sectionKeys
are omitted.sectionKeys
public CommandLine.Model.UsageMessageSpec sectionMap(java.util.Map<java.lang.String,CommandLine.IHelpSectionRenderer> map)
map
- the mapping of section keys to their renderers, must be non-null
.sectionKeys
,
CommandLine.setHelpSectionMap(Map)
public CommandLine.IHelpFactory helpFactory()
IHelpFactory
that is used to construct the usage help message.CommandLine.setHelpFactory(IHelpFactory)
public CommandLine.Model.UsageMessageSpec helpFactory(CommandLine.IHelpFactory helpFactory)
IHelpFactory
to customize the usage help message.helpFactory
- the new help factory. Must be non-null
.UsageMessageSpec
object, to allow method chainingpublic java.lang.String headerHeading()
CommandLine.Command.headerHeading()
, or null.public java.lang.String[] header()
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.public java.lang.String synopsisHeading()
CommandLine.Command.synopsisHeading()
, "Usage: "
by default.public boolean abbreviateSynopsis()
public java.lang.String[] customSynopsis()
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.public java.lang.String descriptionHeading()
CommandLine.Command.descriptionHeading()
, or null.public java.lang.String[] description()
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.public java.lang.String parameterListHeading()
CommandLine.Command.parameterListHeading()
, or null.public java.lang.String optionListHeading()
CommandLine.Command.optionListHeading()
, or null.public boolean sortOptions()
public char requiredOptionMarker()
public boolean showDefaultValues()
public boolean hidden()
true
if this command should not appear in the usage help message of the parent commandpublic java.lang.String commandListHeading()
CommandLine.Command.commandListHeading()
. "Commands:%n"
by default.public java.lang.String footerHeading()
CommandLine.Command.footerHeading()
, or null.public java.lang.String[] footer()
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.public CommandLine.Model.UsageMessageSpec headerHeading(java.lang.String headerHeading)
CommandLine.Command.headerHeading()
, or null.public CommandLine.Model.UsageMessageSpec header(java.lang.String... header)
public CommandLine.Model.UsageMessageSpec synopsisHeading(java.lang.String newValue)
public CommandLine.Model.UsageMessageSpec abbreviateSynopsis(boolean newValue)
public CommandLine.Model.UsageMessageSpec customSynopsis(java.lang.String... customSynopsis)
public CommandLine.Model.UsageMessageSpec descriptionHeading(java.lang.String newValue)
public CommandLine.Model.UsageMessageSpec description(java.lang.String... description)
public CommandLine.Model.UsageMessageSpec parameterListHeading(java.lang.String newValue)
public CommandLine.Model.UsageMessageSpec optionListHeading(java.lang.String newValue)
public CommandLine.Model.UsageMessageSpec sortOptions(boolean newValue)
public CommandLine.Model.UsageMessageSpec requiredOptionMarker(char newValue)
public CommandLine.Model.UsageMessageSpec showDefaultValues(boolean newValue)
public CommandLine.Model.UsageMessageSpec hidden(boolean value)
value
- enable or disable the hidden flagCommandLine.Command.hidden()
public CommandLine.Model.UsageMessageSpec commandListHeading(java.lang.String newValue)
public CommandLine.Model.UsageMessageSpec footerHeading(java.lang.String newValue)
public CommandLine.Model.UsageMessageSpec footer(java.lang.String... footer)
public CommandLine.Model.Messages messages()
null
.public CommandLine.Model.UsageMessageSpec messages(CommandLine.Model.Messages msgs)
msgs
- the new Messages value that encapsulates this command's resource bundle, may be null