Package io.github.qishr.cascara.common.util
Class UsageMessageSpec
java.lang.Object
        io.github.qishr.cascara.common.util.CommandLine.Model.UsageMessageSpec
Enclosing Class:
    io.github.qishr.cascara.common.util.CommandLine.Model
public static class UsageMessageSpec
Models the usage help message specification and can be used to customize the usage help message.
This class provides two ways to customize the usage help message:
Change the text of the predefined sections (this may also be done declaratively using the annotations)
Add custom sections, or remove or re-order predefined sections
The pre-defined sections have getters and setters that return a String (or array of Strings). For example: description and description or header and header.
Changing the section order, or adding custom sections can be accomplished with sectionKeys and sectionMap. This gives complete freedom on how a usage help message section is rendered, but it also means that the IHelpSectionRenderer is responsible for all aspects of rendering the section, including layout and emitting ANSI escape codes. The Help.TextTable and 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 sectionMap 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_EXIT_CODE_LIST_HEADING, help -> help.exitCodeListHeading());
sectionMap.put(SECTION_KEY_EXIT_CODE_LIST, help -> help.exitCodeList());
sectionMap.put(SECTION_KEY_FOOTER_HEADING, help -> help.footerHeading());
sectionMap.put(SECTION_KEY_FOOTER, help -> help.footer());
Field Summary
Constructor Summary
| Constructor | Description |
|---|---|
| UsageMessageSpec() |
Method Summary
| Modifier and Type | Method | Description |
|---|---|---|
| public UsageMessageSpec | width(int newValue) | Sets the maximum usage help message width to the specified value. |
| public UsageMessageSpec | longOptionsMaxWidth(int newValue) | Sets the maximum usage help long options column max width to the specified value. |
| public int | width() | Returns the maximum usage help message width. |
| public int | longOptionsMaxWidth() | Returns the maximum usage help long options column max width to the specified value. |
| public boolean | autoWidth() | Returns whether picocli should attempt to detect the terminal size and adjust the usage help message width to take the full terminal width. |
| public UsageMessageSpec | autoWidth(boolean detectTerminalSize) | Sets whether picocli should attempt to detect the terminal size and adjust the usage help message width to take the full terminal width. |
| public List<String> | sectionKeys() | Returns the section keys in the order that the usage help message should render the sections. |
| public UsageMessageSpec | sectionKeys(List<String> keys) | Sets the section keys in the order that the usage help message should render the sections. |
| public Map<String, IHelpSectionRenderer> | sectionMap() | Returns the map of section keys and renderers used to construct the usage help message. |
| public UsageMessageSpec | sectionMap(Map<String, IHelpSectionRenderer> map) | Sets the map of section keys and renderers used to construct the usage help message to a copy of the specified map. |
| public IHelpFactory | helpFactory() | Returns the IHelpFactory that is used to construct the usage help message. |
| public UsageMessageSpec | helpFactory(IHelpFactory helpFactory) | Sets a new IHelpFactory to customize the usage help message. |
| public String | headerHeading() | Returns the optional heading preceding the header section. |
| public String[] | header() | Returns the optional header lines displayed at the top of the help message. |
| public String | synopsisHeading() | Returns the optional heading preceding the synopsis. |
| public String | synopsisSubcommandLabel() | Returns the String representing the subcommands in the synopsis. |
| public double | synopsisAutoIndentThreshold() | Returns the fraction of the usage help width.width that is the threshold up to which the 2nd line and subsequent lines of a multi-line synopsis should be aligned to the end of the command name. |
| public int | synopsisIndent() | Returns the indentation to use on the 2nd line and subsequent lines of a multi-line synopsis when the length of the synopsis heading and the fully qualified command name exceed the width.width times the synopsisAutoIndentThreshold.synopsisAutoIndentThreshold, -1 by default. |
| public boolean | abbreviateSynopsis() | Returns whether the synopsis line(s) should show an abbreviated synopsis without detailed option names. |
| public String[] | customSynopsis() | Returns the optional custom synopsis lines to use instead of the auto-generated synopsis. |
| public String | descriptionHeading() | Returns the optional heading preceding the description section. |
| public String[] | description() | Returns the optional text lines to use as the description of the help message, displayed between the synopsis and the options list. |
| public String | parameterListHeading() | Returns the optional heading preceding the parameter list. |
| public String | optionListHeading() | Returns the optional heading preceding the options list. |
| public boolean | sortOptions() | Returns whether the options list in the usage help message should be sorted alphabetically. |
| public boolean | sortSynopsis() | Returns whether the options in the synopsis should be sorted alphabetically. |
| public char | requiredOptionMarker() | Returns the character used to prefix required options in the options list. |
| public boolean | showDefaultValues() | Returns whether the options list in the usage help message should show default values for all non-boolean options. |
| public boolean | showAtFileInUsageHelp() | Sets whether to show a [@<filename>...] entry in the synopsis and parameter list of the usage help message. |
| public boolean | showEndOfOptionsDelimiterInUsageHelp() | Sets whether to show a [--] (End of Options) entry in the synopsis and options list of the usage help message. |
| public boolean | hidden() | Returns whether this command should be hidden from the usage help message of the parent command. |
| public String | commandListHeading() | Returns the optional heading preceding the subcommand list. |
| public String | exitCodeListHeading() | Returns the optional heading preceding the exit codes section, may contain "%n" line separators. |
| public Map<String, String> | exitCodeList() | Returns an unmodifiable map with values to be displayed in the exit codes section: keys are exit codes, values are descriptions. |
| public static Map<String, String> | keyValuesMap(String[] entries) | Creates and returns a Map that contains an entry for each specified String that is in "key:value" format. |
| public String | footerHeading() | Returns the optional heading preceding the footer section. |
| public String[] | footer() | Returns the optional footer text lines displayed at the bottom of the help message. |
| public UsageMessageSpec | headerHeading(String headerHeading) | Sets the heading preceding the header section. |
| public UsageMessageSpec | header(String[] header) | Sets the optional header lines displayed at the top of the help message. |
| public UsageMessageSpec | synopsisHeading(String newValue) | Sets the optional heading preceding the synopsis. |
| public UsageMessageSpec | synopsisSubcommandLabel(String newValue) | Sets the String representing the subcommands in the synopsis. |
| public UsageMessageSpec | synopsisAutoIndentThreshold(double newValue) | Sets the fraction of the usage help width.width that is the threshold up to which the 2nd line and subsequent lines of a multi-line synopsis should be aligned to the end of the command name. |
| public UsageMessageSpec | synopsisIndent(int newValue) | Sets the indentation to use on the 2nd line and subsequent lines of a multi-line synopsis when the length of the synopsis heading and the fully qualified command name exceed the synopsisAutoIndentThreshold.synopsisAutoIndentThreshold fraction of the width.width, -1 by default. |
| public UsageMessageSpec | abbreviateSynopsis(boolean newValue) | Sets whether the synopsis line(s) should show an abbreviated synopsis without detailed option names. |
| public UsageMessageSpec | customSynopsis(String[] customSynopsis) | Sets the optional custom synopsis lines to use instead of the auto-generated synopsis. |
| public UsageMessageSpec | descriptionHeading(String newValue) | Sets the heading preceding the description section. |
| public UsageMessageSpec | description(String[] description) | Sets the optional text lines to use as the description of the help message, displayed between the synopsis and the options list. |
| public UsageMessageSpec | parameterListHeading(String newValue) | Sets the optional heading preceding the parameter list. |
| public UsageMessageSpec | optionListHeading(String newValue) | Sets the heading preceding the options list. |
| public UsageMessageSpec | sortOptions(boolean newValue) | Sets whether the options list in the usage help message should be sorted alphabetically. |
| public UsageMessageSpec | sortSynopsis(boolean newValue) | Sets whether the options in the synopsis should be sorted alphabetically. |
| public UsageMessageSpec | requiredOptionMarker(char newValue) | Sets the character used to prefix required options in the options list. |
| public UsageMessageSpec | showDefaultValues(boolean newValue) | Sets whether the options list in the usage help message should show default values for all non-boolean options. |
| public UsageMessageSpec | showAtFileInUsageHelp(boolean newValue) | Sets whether to show a [@<filename>...] entry in the synopsis and parameter list of the usage help message. |
| public UsageMessageSpec | showEndOfOptionsDelimiterInUsageHelp(boolean newValue) | Sets whether to show a [--] (End of Options) entry in the synopsis and options list of the usage help message. |
| public 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. |
| public UsageMessageSpec | commandListHeading(String newValue) | Sets the optional heading preceding the subcommand list. |
| public UsageMessageSpec | exitCodeListHeading(String newValue) | Sets the optional heading preceding the exit codes section, may contain "%n" line separators. |
| public UsageMessageSpec | exitCodeList(Map<String, String> newValue) | Sets the values to be displayed in the exit codes section: keys are exit codes, values are descriptions. |
| public UsageMessageSpec | footerHeading(String newValue) | Sets the optional heading preceding the footer section. |
| public UsageMessageSpec | footer(String[] footer) | Sets the optional footer text lines displayed at the bottom of the help message. |
| public Messages | messages() | Returns the Messages for this usage help message specification, or null. |
| public UsageMessageSpec | messages(Messages msgs) | Sets the Messages for this usageMessage specification, and returns this UsageMessageSpec. |
| public boolean | adjustLineBreaksForWideCJKCharacters() | Returns whether line breaks should take wide Chinese, Japanese and Korean characters into account for line-breaking purposes. |
| public UsageMessageSpec | adjustLineBreaksForWideCJKCharacters(boolean adjustForWideChars) | Sets whether line breaks should take wide Chinese, Japanese and Korean characters into account, and returns this UsageMessageSpec. |
Field Details
DEFAULT_USAGE_WIDTH
public static final int DEFAULT_USAGE_WIDTH
Constant holding the default usage message width: .
SECTION_KEY_AT_FILE_PARAMETER
public static final String SECTION_KEY_AT_FILE_PARAMETER
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the @-file parameter list section.The default renderer for this section calls Help#atFileParameterList().
SECTION_KEY_COMMAND_LIST
public static final String SECTION_KEY_COMMAND_LIST
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Subcommand List section.The default renderer for this section calls Help#commandList().
SECTION_KEY_COMMAND_LIST_HEADING
public static final String SECTION_KEY_COMMAND_LIST_HEADING
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Subcommand List Heading section.The default renderer for this section calls Help.commandListHeading.
SECTION_KEY_DESCRIPTION
public static final String SECTION_KEY_DESCRIPTION
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Description section.The default renderer for this section calls Help.description.
SECTION_KEY_DESCRIPTION_HEADING
public static final String SECTION_KEY_DESCRIPTION_HEADING
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Description Heading section.The default renderer for this section calls Help.descriptionHeading.
SECTION_KEY_END_OF_OPTIONS
public static final String SECTION_KEY_END_OF_OPTIONS
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the -- End of Options list section.The default renderer for this section calls Help#endOfOptionsList().
SECTION_KEY_EXIT_CODE_LIST
public static final String SECTION_KEY_EXIT_CODE_LIST
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Exit Code List section.The default renderer for this section calls Help.exitCodeList.
SECTION_KEY_EXIT_CODE_LIST_HEADING
public static final String SECTION_KEY_EXIT_CODE_LIST_HEADING
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Exit Code List Heading section.The default renderer for this section calls Help.exitCodeListHeading.
SECTION_KEY_FOOTER
public static final String SECTION_KEY_FOOTER
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Footer section.The default renderer for this section calls Help.footer.
SECTION_KEY_FOOTER_HEADING
public static final String SECTION_KEY_FOOTER_HEADING
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Footer Heading section.The default renderer for this section calls Help.footerHeading.
SECTION_KEY_HEADER
public static final String SECTION_KEY_HEADER
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Header section.The default renderer for this section calls Help.header.
SECTION_KEY_HEADER_HEADING
public static final String SECTION_KEY_HEADER_HEADING
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Header Heading section.The default renderer for this section calls Help.headerHeading.
SECTION_KEY_OPTION_LIST
public static final String SECTION_KEY_OPTION_LIST
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Option List section.The default renderer for this section calls Help#optionList().
SECTION_KEY_OPTION_LIST_HEADING
public static final String SECTION_KEY_OPTION_LIST_HEADING
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Option List Heading section.The default renderer for this section calls Help.optionListHeading.
SECTION_KEY_PARAMETER_LIST
public static final String SECTION_KEY_PARAMETER_LIST
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Parameter List section.The default renderer for this section calls Help#parameterList().
SECTION_KEY_PARAMETER_LIST_HEADING
public static final String SECTION_KEY_PARAMETER_LIST_HEADING
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Parameter List Heading section.The default renderer for this section calls Help.parameterListHeading.
SECTION_KEY_SYNOPSIS
public static final String SECTION_KEY_SYNOPSIS
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Synopsis section.The default renderer for this section calls Help#synopsis(int).
SECTION_KEY_SYNOPSIS_HEADING
public static final String SECTION_KEY_SYNOPSIS_HEADING
sectionKeys.sectionKeys to sectionMap.sectionMap the IHelpSectionRenderer for the Synopsis Heading section.The default renderer for this section calls Help.synopsisHeading.
Method Details
width
public UsageMessageSpec width(int newValue)
Sets the maximum usage help message width to the specified value.Longer values are wrapped.
Parameters:
newValue - the new maximum usage help message width. Must be 55 or greater.
Returns:
this UsageMessageSpec for method chaining
longOptionsMaxWidth
public UsageMessageSpec longOptionsMaxWidth(int newValue)
Sets the maximum usage help long options column max width to the specified value.This value controls the maximum width of the long options column: any positional parameter labels or long options that are longer than the specified value will overflow into the description column, and cause the description to be displayed on the next line.
Parameters:
newValue - the new maximum usage help long options column max width. Must be 20 or greater, otherwise the new value will be ignored.
Returns:
this UsageMessageSpec for method chaining
Since:
4.2
width
public int width()
Returns the maximum usage help message width.Derived from system property "picocli.usage.width"
if set, otherwise returns the value set via the width.width method, or if not set, the default width.
Returns:
the maximum usage help message width. Never returns less than 55.
longOptionsMaxWidth
public int longOptionsMaxWidth()
Returns the maximum usage help long options column max width to the specified value.This value controls the maximum width of the long options column: any positional parameter labels or long options that are longer than the specified value will overflow into the description column, and cause the description to be displayed on the next line.
Returns:
the new maximum usage help long options column max width. Always 20 or greater.
Since:
4.2
autoWidth
public boolean autoWidth()
Returns whether picocli should attempt to detect the terminal size and adjust the usage help message width
to take the full terminal width.End users may enable this by setting system property "picocli.usage.width" to AUTO,
and may disable this by setting this system property to a width.width.
This feature requires Java 7 or greater. The default is false.
Since:
4.0
See Also:
autoWidth
public UsageMessageSpec autoWidth(boolean detectTerminalSize)
Sets whether picocli should attempt to detect the terminal size and adjust the usage help message width
to take the full terminal width.The default is false.
Parameters:
detectTerminalSize - whether picocli should attempt to detect the terminal size
Since:
4.0
See Also:
sectionKeys
public List<String> sectionKeys()
Returns the section keys in the order that the usage help message should render the sections.This ordering may be modified with the sectionKeys.sectionKeys. The default keys are (in order):
UsageMessageSpec#SECTION_KEY_HEADER_HEADING UsageMessageSpec#SECTION_KEY_HEADER UsageMessageSpec#SECTION_KEY_SYNOPSIS_HEADING UsageMessageSpec#SECTION_KEY_SYNOPSIS UsageMessageSpec#SECTION_KEY_DESCRIPTION_HEADING UsageMessageSpec#SECTION_KEY_DESCRIPTION UsageMessageSpec#SECTION_KEY_PARAMETER_LIST_HEADING UsageMessageSpec#SECTION_KEY_AT_FILE_PARAMETER UsageMessageSpec#SECTION_KEY_PARAMETER_LIST UsageMessageSpec#SECTION_KEY_OPTION_LIST_HEADING UsageMessageSpec#SECTION_KEY_OPTION_LIST UsageMessageSpec#SECTION_KEY_END_OF_OPTIONS UsageMessageSpec#SECTION_KEY_COMMAND_LIST_HEADING UsageMessageSpec#SECTION_KEY_COMMAND_LIST UsageMessageSpec#SECTION_KEY_EXIT_CODE_LIST_HEADING UsageMessageSpec#SECTION_KEY_EXIT_CODE_LIST UsageMessageSpec#SECTION_KEY_FOOTER_HEADING UsageMessageSpec#SECTION_KEY_FOOTER
Since:
3.9
sectionKeys
public UsageMessageSpec sectionKeys(List<String> keys)
Sets the section keys in the order that the usage help message should render the sections.
Since:
3.9
See Also:
sectionMap
public Map<String, IHelpSectionRenderer> sectionMap()
Returns the map of section keys and renderers used to construct the usage help message.The usage help message can be customized by adding, replacing and removing section renderers from this map. Sections can be reordered with the sectionKeys.sectionKeys. Sections that are either not in this map or not in the list returned by sectionKeys.sectionKeys are omitted.
Since:
3.9
See Also:
sectionMap
public UsageMessageSpec sectionMap(Map<String, IHelpSectionRenderer> map)
Sets the map of section keys and renderers used to construct the usage help message to a copy of the specified map.
Parameters:
map - the mapping of section keys to their renderers, must be non-null.
Returns:
this UsageMessageSpec for method chaining
Since:
3.9
See Also:
helpFactory
public IHelpFactory helpFactory()
Returns the IHelpFactory that is used to construct the usage help message.
Since:
3.9
See Also:
helpFactory
public UsageMessageSpec helpFactory(IHelpFactory helpFactory)
Sets a new IHelpFactory to customize the usage help message.
Parameters:
helpFactory - the new help factory. Must be non-null.
Returns:
this UsageMessageSpec object, to allow method chaining
headerHeading
public String headerHeading()
Returns the optional heading preceding the header section.Initialized from Command.headerHeading, or "" (empty string).
header
public String[] header()
Returns the 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 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.
synopsisHeading
public String synopsisHeading()
Returns the optional heading preceding the synopsis.Initialized from Command.synopsisHeading, "Usage: " by default.
synopsisSubcommandLabel
public String synopsisSubcommandLabel()
Returns the String representing the subcommands in the synopsis.Initialized from Command.synopsisSubcommandLabel, "[COMMANDS]" by default.
Since:
4.0
synopsisAutoIndentThreshold
public double synopsisAutoIndentThreshold()
Returns the fraction of the usage help width.width that is the threshold up to which
the 2nd line and subsequent lines of a multi-line synopsis should be aligned to the end of the command name.The default value of this attribute is 0.5.
If the length of the synopsis heading plus the length of the fully qualified command name exceeds this fraction of the width,
the 2nd and subsequent rows of a multi-line synopsis will be aligned to the synopsisIndent.synopsisIndent instead of the end of the command name.
Since:
4.0
synopsisIndent
public int synopsisIndent()
Returns the indentation to use on the 2nd line and subsequent lines of a multi-line synopsis
when the length of the synopsis heading and the fully qualified command name exceed the width.width times the synopsisAutoIndentThreshold.synopsisAutoIndentThreshold, -1 by default.A negative value for this option means that the 2nd line and subsequent lines are aligned to the synopsis heading length.
A positive value means the exact number of spaces to indent for the 2nd line and subsequent lines of the synopsis.
Since:
4.0
abbreviateSynopsis
public boolean abbreviateSynopsis()
Returns whether the synopsis line(s) should show an abbreviated synopsis without detailed option names.
customSynopsis
public String[] customSynopsis()
Returns the optional custom synopsis lines to use instead of the auto-generated synopsis.Initialized from 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.
descriptionHeading
public String descriptionHeading()
Returns the optional heading preceding the description section.Initialized from Command.descriptionHeading, or null.
description
public String[] description()
Returns the optional text lines to use as the description of the help message, displayed between the synopsis and the
options list.Initialized from 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.
parameterListHeading
public String parameterListHeading()
Returns the optional heading preceding the parameter list.Initialized from Command.parameterListHeading, or null.
optionListHeading
public String optionListHeading()
Returns the optional heading preceding the options list.Initialized from Command.optionListHeading, or null.
sortOptions
public boolean sortOptions()
Returns whether the options list in the usage help message should be sorted alphabetically.
sortSynopsis
public boolean sortSynopsis()
Returns whether the options in the synopsis should be sorted alphabetically.
Since:
4.7.8-SNAPSHOT
requiredOptionMarker
public char requiredOptionMarker()
Returns the character used to prefix required options in the options list.
showDefaultValues
public boolean showDefaultValues()
Returns whether the options list in the usage help message should show default values for all non-boolean options.
showAtFileInUsageHelp
public boolean showAtFileInUsageHelp()
Sets whether to show a [@<filename>...] entry in the synopsis and parameter list of the usage help message.(The entry is not shown if expanding parameter files is disabled.)
Since:
4.2
See Also:
showEndOfOptionsDelimiterInUsageHelp
public boolean showEndOfOptionsDelimiterInUsageHelp()
Sets whether to show a [--] (End of Options) entry in the synopsis and options list of the usage help message.
Since:
4.3
See Also:
showEndOfOptionsDelimiterInUsageHelp
hidden
public boolean hidden()
Returns whether this command should be hidden from the usage help message of the parent command.
Returns:
true if this command should not appear in the usage help message of the parent command
commandListHeading
public String commandListHeading()
Returns the optional heading preceding the subcommand list.Initialized from Command.commandListHeading. "Commands:%n" by default.
exitCodeListHeading
public String exitCodeListHeading()
Returns the optional heading preceding the exit codes section, may contain "%n" line separators."" (empty string) by default.
exitCodeList
public Map<String, String> exitCodeList()
Returns an unmodifiable map with values to be displayed in the exit codes section: keys are exit codes, values are descriptions.Descriptions may contain "%n" line separators.
Callers may be interested in the UsageMessageSpec.keyValuesMap method for creating a map from a list of "key:value" Strings.
This may be configured in a resource bundle by listing up multiple "key:value" pairs. For example:
usage.exitCodeList.0 = 0:Successful program execution. usage.exitCodeList.1 = 64:Invalid input: an unknown option or invalid parameter was specified. usage.exitCodeList.2 = 70:Execution exception: an exception occurred while executing the business logic.
Returns:
an unmodifiable map with values to be displayed in the exit codes section, or an empty map if no exit codes are exitCodeList.exitCodeList.
Since:
4.0
See Also:
keyValuesMap
public static Map<String, String> keyValuesMap(String[] entries)
Creates and returns a Map that contains an entry for each specified String that is in "key:value" format.
Parameters:
entries - the strings to process; values that are not in "key:value" format are ignored
Returns:
a Map with an entry for each line, preserving the input order
Since:
4.0
footerHeading
public String footerHeading()
Returns the optional heading preceding the footer section.Initialized from Command.footerHeading, or "" (empty string).
footer
public String[] footer()
Returns the optional footer text lines displayed at the bottom of the help message.Initialized from
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.
headerHeading
public UsageMessageSpec headerHeading(String headerHeading)
Sets the heading preceding the header section.Initialized from Command.headerHeading, or null.
Returns:
this UsageMessageSpec for method chaining
header
public UsageMessageSpec header(String[] header)
Sets the optional header lines displayed at the top of the help message.For subcommands, the first header line is displayed in the list of commands.
Returns:
this UsageMessageSpec for method chaining
synopsisHeading
public UsageMessageSpec synopsisHeading(String newValue)
Sets the optional heading preceding the synopsis.
Returns:
this UsageMessageSpec for method chaining
synopsisSubcommandLabel
public UsageMessageSpec synopsisSubcommandLabel(String newValue)
Sets the String representing the subcommands in the synopsis.
Returns:
this UsageMessageSpec for method chaining
Since:
4.0
synopsisAutoIndentThreshold
public UsageMessageSpec synopsisAutoIndentThreshold(double newValue)
Sets the fraction of the usage help width.width that is the threshold up to which
the 2nd line and subsequent lines of a multi-line synopsis should be aligned to the end of the command name.The default value of this attribute is 0.5.
If the length of the synopsis heading plus the length of the fully qualified command name exceeds this fraction of the width,
the 2nd and subsequent rows of a multi-line synopsis will be aligned to the synopsisIndent.synopsisIndent instead of the end of the command name.
Parameters:
newValue - the new threshold value. Must be a value between 0.0 and 0.9, inclusive
Returns:
this UsageMessageSpec for method chaining
Since:
4.0
synopsisIndent
public UsageMessageSpec synopsisIndent(int newValue)
Sets the indentation to use on the 2nd line and subsequent lines of a multi-line synopsis
when the length of the synopsis heading and the fully qualified command name exceed the synopsisAutoIndentThreshold.synopsisAutoIndentThreshold fraction of the width.width, -1 by default.A negative value for this option means that the 2nd line and subsequent lines are aligned to the synopsis heading length.
A positive value means the exact number of spaces to indent for the 2nd line and subsequent lines of the synopsis.
Returns:
this UsageMessageSpec for method chaining
Since:
4.0
abbreviateSynopsis
public UsageMessageSpec abbreviateSynopsis(boolean newValue)
Sets whether the synopsis line(s) should show an abbreviated synopsis without detailed option names.
Returns:
this UsageMessageSpec for method chaining
customSynopsis
public UsageMessageSpec customSynopsis(String[] customSynopsis)
Sets the optional custom synopsis lines to use instead of the auto-generated synopsis.
Returns:
this UsageMessageSpec for method chaining
descriptionHeading
public UsageMessageSpec descriptionHeading(String newValue)
Sets the heading preceding the description section.
Returns:
this UsageMessageSpec for method chaining
description
public UsageMessageSpec description(String[] description)
Sets the optional text lines to use as the description of the help message, displayed between the synopsis and the options list.
Returns:
this UsageMessageSpec for method chaining
parameterListHeading
public UsageMessageSpec parameterListHeading(String newValue)
Sets the optional heading preceding the parameter list.
Returns:
this UsageMessageSpec for method chaining
optionListHeading
public UsageMessageSpec optionListHeading(String newValue)
Sets the heading preceding the options list.
Returns:
this UsageMessageSpec for method chaining
sortOptions
public UsageMessageSpec sortOptions(boolean newValue)
Sets whether the options list in the usage help message should be sorted alphabetically.
Returns:
this UsageMessageSpec for method chaining
sortSynopsis
public UsageMessageSpec sortSynopsis(boolean newValue)
Sets whether the options in the synopsis should be sorted alphabetically.
Returns:
this UsageMessageSpec for method chaining
Since:
4.7.8-SNAPSHOT
requiredOptionMarker
public UsageMessageSpec requiredOptionMarker(char newValue)
Sets the character used to prefix required options in the options list.
Returns:
this UsageMessageSpec for method chaining
showDefaultValues
public UsageMessageSpec showDefaultValues(boolean newValue)
Sets whether the options list in the usage help message should show default values for all non-boolean options.
Returns:
this UsageMessageSpec for method chaining
showAtFileInUsageHelp
public UsageMessageSpec showAtFileInUsageHelp(boolean newValue)
Sets whether to show a [@<filename>...] entry in the synopsis and parameter list of the usage help message.(The entry is not shown if expanding parameter files is disabled.)
Returns:
this UsageMessageSpec for method chaining
Since:
4.2
See Also:
showEndOfOptionsDelimiterInUsageHelp
public UsageMessageSpec showEndOfOptionsDelimiterInUsageHelp(boolean newValue)
Sets whether to show a [--] (End of Options) entry in the synopsis and options list of the usage help message.
Returns:
this UsageMessageSpec for method chaining
Since:
4.3
See Also:
showEndOfOptionsDelimiterInUsageHelp
hidden
public 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.
Parameters:
value - enable or disable the hidden flag
Returns:
this UsageMessageSpec for method chaining
See Also:
commandListHeading
public UsageMessageSpec commandListHeading(String newValue)
Sets the optional heading preceding the subcommand list.
Returns:
this UsageMessageSpec for method chaining
exitCodeListHeading
public UsageMessageSpec exitCodeListHeading(String newValue)
Sets the optional heading preceding the exit codes section, may contain "%n" line separators."" (empty string) by default.
Since:
4.0
exitCodeList
public UsageMessageSpec exitCodeList(Map<String, String> newValue)
Sets the values to be displayed in the exit codes section: keys are exit codes, values are descriptions.Descriptions may contain "%n" line separators.
This may be configured in a resource bundle by listing up multiple "key:value" pairs. For example:
usage.exitCodeList.0 = 0:Successful program execution. usage.exitCodeList.1 = 64:Invalid input: an unknown option or invalid parameter was specified. usage.exitCodeList.2 = 70:Execution exception: an exception occurred while executing the business logic.
Parameters:
newValue - a map with values to be displayed in the exit codes section
Since:
4.0
See Also:
footerHeading
public UsageMessageSpec footerHeading(String newValue)
Sets the optional heading preceding the footer section.
Returns:
this UsageMessageSpec for method chaining
footer
public UsageMessageSpec footer(String[] footer)
Sets the optional footer text lines displayed at the bottom of the help message.
Returns:
this UsageMessageSpec for method chaining
messages
public Messages messages()
Returns the Messages for this usage help message specification, or null.
Returns:
the Messages object that encapsulates this command's resource bundle
Since:
3.6
messages
public UsageMessageSpec messages(Messages msgs)
Sets the Messages for this usageMessage specification, and returns this UsageMessageSpec.
Parameters:
msgs - the new Messages value that encapsulates this command's resource bundle, may be null
Since:
3.6
adjustLineBreaksForWideCJKCharacters
public boolean adjustLineBreaksForWideCJKCharacters()
Returns whether line breaks should take wide Chinese, Japanese and Korean characters into account for line-breaking purposes.
Returns:
true if wide Chinese, Japanese and Korean characters are counted as double the size of other characters for line-breaking purposes
Since:
4.0
adjustLineBreaksForWideCJKCharacters
public UsageMessageSpec adjustLineBreaksForWideCJKCharacters(boolean adjustForWideChars)
Sets whether line breaks should take wide Chinese, Japanese and Korean characters into account, and returns this UsageMessageSpec.
Parameters:
adjustForWideChars - if true, wide Chinese, Japanese and Korean characters are counted as double the size of other characters for line-breaking purposes
Since:
4.0