Class CommandLine.Model.UsageMessageSpec
- Enclosing class:
CommandLine.Model
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(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_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());
- Since:
- 3.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Boolean
private Boolean
private Boolean
private Integer
private String
private String[]
(package private) static final Boolean
Constant Boolean holding the default setting for whether to abbreviate the synopsis:.
(package private) static final Boolean
Constant Boolean holding the default setting for whether line breaks should take wide CJK characters into account:.
(package private) static final String
Constant String holding the default command list heading:"Commands:%n"
.(package private) static final Boolean
Constant Boolean holding the default setting for whether this command should be listed in the usage help of the parent command:.
(package private) static final String[]
(package private) static final char
Constant String holding the default string that separates options from option parameters:' '
(' ').(package private) static final Boolean
Constant Boolean holding the default setting for whether to show an entry for @-files in the usage help message.(package private) static final Boolean
Constant Boolean holding the default setting for whether to show default values in the usage help message:.
(package private) static final Boolean
Constant Boolean holding the default setting for whether to show an entry for the--
End of Options delimiter in the usage help message.(package private) static final String
(package private) static final Boolean
Constant Boolean holding the default setting for whether to sort the options alphabetically:.
(package private) static final Boolean
Constant Boolean holding the default setting for whether to sort options in the synopsis alphabetically:.
private static final double
(package private) static final String
Constant String holding the default synopsis heading:"Usage: "
.private static final int
(package private) static final String
Constant String holding the default synopsis subcommands:"[COMMAND]"
.(package private) static final Boolean
Constant Boolean holding the default setting for whether to attempt to adjust the width to the terminal width:.
(package private) static final int
static final int
Constant holding the default usage message width:80
.private String[]
private String
private String
private String[]
private String[]
private String
private String[]
private String
private CommandLine.IHelpFactory
private Map
<String, CommandLine.IHelpSectionRenderer> private Boolean
private final CommandLine.Model.Interpolator
private Integer
private static final double
private CommandLine.Model.Messages
private static final int
private String
private String
private Character
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
private Boolean
private Boolean
private Boolean
private Boolean
private Boolean
private Double
private String
private Integer
private String
private Integer
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
Returns whether the synopsis line(s) should show an abbreviated synopsis without detailed option names.abbreviateSynopsis
(boolean newValue) Sets whether the synopsis line(s) should show an abbreviated synopsis without detailed option names.boolean
Returns whether line breaks should take wide Chinese, Japanese and Korean characters into account for line-breaking purposes.adjustLineBreaksForWideCJKCharacters
(boolean adjustForWideChars) Sets whether line breaks should take wide Chinese, Japanese and Korean characters into account, and returns this UsageMessageSpec.private String[]
boolean
Returns whether picocli should attempt to detect the terminal size and adjust the usage help message width to take the full terminal width.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.Returns the optional heading preceding the subcommand list.commandListHeading
(String newValue) Sets the optional heading preceding the subcommand list.private Map
<String, CommandLine.IHelpSectionRenderer> Returns the help section renderers for the predefined section keys.String[]
Returns the optional custom synopsis lines to use instead of the auto-generated synopsis.customSynopsis
(String... customSynopsis) Sets the optional custom synopsis lines to use instead of the auto-generated synopsis.String[]
Returns the optional text lines to use as the description of the help message, displayed between the synopsis and the options list.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 the optional heading preceding the description section.descriptionHeading
(String newValue) Sets the heading preceding the description section.private static int
Returns an unmodifiable map with values to be displayed in the exit codes section: keys are exit codes, values are descriptions.exitCodeList
(Map<String, String> newValue) Sets the values to be displayed in the exit codes section: keys are exit codes, values are descriptions.Returns the optional heading preceding the exit codes section, may contain"%n"
line separators.exitCodeListHeading
(String newValue) Sets the optional heading preceding the exit codes section, may contain"%n"
line separators.String[]
footer()
Returns the optional footer text lines displayed at the bottom of the help message.Sets the optional footer text lines displayed at the bottom of the help message.Returns the optional heading preceding the footer section.footerHeading
(String newValue) Sets the optional heading preceding the footer section.private int
getSysPropertyWidthOrDefault
(int defaultWidth, boolean detectTerminalSize) private static int
String[]
header()
Returns the optional header lines displayed at the top of the help message.Sets the optional header lines displayed at the top of the help message.Returns the optional heading preceding the header section.headerHeading
(String headerHeading) Sets the heading preceding the header section.Returns theIHelpFactory
that is used to construct the usage help message.helpFactory
(CommandLine.IHelpFactory helpFactory) Sets a newIHelpFactory
to customize the usage help message.boolean
hidden()
Returns whether this command should be hidden from the usage help message of the parent command.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.(package private) void
initFrom
(CommandLine.Model.UsageMessageSpec settings, CommandLine.Model.CommandSpec commandSpec) (package private) void
initFromMixin
(CommandLine.Model.UsageMessageSpec mixin, CommandLine.Model.CommandSpec commandSpec) private String
interpolate
(String value) private String[]
interpolate
(String[] values) (package private) static boolean
isCodePointCJK
(int codePoint) Given a codePoint, is this codePoint considered to be a CJK character? Shamelessly stolen from StackOverflow where it was contributed by user Rakesh N.private static boolean
keyValuesMap
(String... entries) Creates and returns aMap
that contains an entry for each specified String that is in"key:value"
format.int
Returns the maximum usage help long options column max width to the specified value.longOptionsMaxWidth
(int newValue) Sets the maximum usage help long options column max width to the specified value.messages()
Returns the Messages for this usage help message specification, ornull
.Sets the Messages for this usageMessage specification, and returns this UsageMessageSpec.Returns the optional heading preceding the options list.optionListHeading
(String newValue) Sets the heading preceding the options list.Returns the optional heading preceding the parameter list.parameterListHeading
(String newValue) Sets the optional heading preceding the parameter list.char
Returns the character used to prefix required options in the options list.requiredOptionMarker
(char newValue) Sets the character used to prefix required options in the options list.private String[]
resourceArr
(String key) private String
resourceStr
(String key) Returns the section keys in the order that the usage help message should render the sections.sectionKeys
(List<String> keys) Sets the section keys in the order that the usage help message should render the sections.Returns the map of section keys and renderers used to construct the usage help message.Sets the map of section keys and renderers used to construct the usage help message to a copy of the specified map.private static boolean
shouldDetectTerminalSize
(boolean autoWidthEnabledInApplication) boolean
Sets whether to show a[@<filename>...]
entry in the synopsis and parameter list of the usage help message.showAtFileInUsageHelp
(boolean newValue) Sets whether to show a[@<filename>...]
entry in the synopsis and parameter list of the usage help message.boolean
Returns whether the options list in the usage help message should show default values for all non-boolean options.showDefaultValues
(boolean newValue) Sets whether the options list in the usage help message should show default values for all non-boolean options.boolean
Sets whether to show a[--]
(End of Options) entry in the synopsis and options list of the usage help message.showEndOfOptionsDelimiterInUsageHelp
(boolean newValue) Sets whether to show a[--]
(End of Options) entry in the synopsis and options list of the usage help message.boolean
Returns whether the options list in the usage help message should be sorted alphabetically.sortOptions
(boolean newValue) Sets whether the options list in the usage help message should be sorted alphabetically.boolean
Returns whether the options in the synopsis should be sorted alphabetically.sortSynopsis
(boolean newValue) Sets whether the options in the synopsis should be sorted alphabetically.private String
double
Returns the fraction of the usage helpwidth()
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.synopsisAutoIndentThreshold
(double newValue) Sets the fraction of the usage helpwidth()
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.Returns the optional heading preceding the synopsis.synopsisHeading
(String newValue) Sets the optional heading preceding the synopsis.int
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 thewidth()
times thesynopsisAutoIndentThreshold()
,-1
by default.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 thesynopsisAutoIndentThreshold()
fraction of thewidth()
,-1
by default.Returns the String representing the subcommands in the synopsis.synopsisSubcommandLabel
(String newValue) Sets the String representing the subcommands in the synopsis.(package private) void
updateFromCommand
(CommandLine.Command cmd, CommandLine.Model.CommandSpec commandSpec, boolean loadResourceBundle) int
width()
Returns the maximum usage help message width.width
(int newValue) Sets the maximum usage help message width to the specified value.
-
Field Details
-
SECTION_KEY_HEADER_HEADING
Section key to control the section renderer for the Header Heading section. The default renderer for this section callsCommandLine.Help.headerHeading(Object...)
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_HEADER
Section key to control the section renderer for the Header section. The default renderer for this section callsCommandLine.Help.header(Object...)
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_SYNOPSIS_HEADING
Section key to control the section renderer for the Synopsis Heading section. The default renderer for this section callsCommandLine.Help.synopsisHeading(Object...)
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_SYNOPSIS
Section key to control the section renderer for the Synopsis section. The default renderer for this section callsCommandLine.Help.synopsis(int)
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_DESCRIPTION_HEADING
Section key to control the section renderer for the Description Heading section. The default renderer for this section callsCommandLine.Help.descriptionHeading(Object...)
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_DESCRIPTION
Section key to control the section renderer for the Description section. The default renderer for this section callsCommandLine.Help.description(Object...)
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_PARAMETER_LIST_HEADING
Section key to control the section renderer for the Parameter List Heading section. The default renderer for this section callsCommandLine.Help.parameterListHeading(Object...)
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_AT_FILE_PARAMETER
Section key to control the section renderer for the @-file parameter list section. The default renderer for this section callsCommandLine.Help.atFileParameterList()
.- Since:
- 4.2
- See Also:
-
SECTION_KEY_PARAMETER_LIST
Section key to control the section renderer for the Parameter List section. The default renderer for this section callsCommandLine.Help.parameterList()
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_OPTION_LIST_HEADING
Section key to control the section renderer for the Option List Heading section. The default renderer for this section callsCommandLine.Help.optionListHeading(Object...)
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_OPTION_LIST
Section key to control the section renderer for the Option List section. The default renderer for this section callsCommandLine.Help.optionList()
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_END_OF_OPTIONS
Section key to control the section renderer for the--
End of Options list section. The default renderer for this section callsCommandLine.Help.endOfOptionsList()
.- Since:
- 4.3
- See Also:
-
SECTION_KEY_COMMAND_LIST_HEADING
Section key to control the section renderer for the Subcommand List Heading section. The default renderer for this section callsCommandLine.Help.commandListHeading(Object...)
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_COMMAND_LIST
Section key to control the section renderer for the Subcommand List section. The default renderer for this section callsCommandLine.Help.commandList()
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_EXIT_CODE_LIST_HEADING
Section key to control the section renderer for the Exit Code List Heading section. The default renderer for this section callsCommandLine.Help.exitCodeListHeading(Object...)
.- Since:
- 4.0
- See Also:
-
SECTION_KEY_EXIT_CODE_LIST
Section key to control the section renderer for the Exit Code List section. The default renderer for this section callsCommandLine.Help.exitCodeList()
.- Since:
- 4.0
- See Also:
-
SECTION_KEY_FOOTER_HEADING
Section key to control the section renderer for the Footer Heading section. The default renderer for this section callsCommandLine.Help.footerHeading(Object...)
.- Since:
- 3.9
- See Also:
-
SECTION_KEY_FOOTER
Section key to control the section renderer for the Footer section. The default renderer for this section callsCommandLine.Help.footer(Object...)
.- Since:
- 3.9
- See Also:
-
DEFAULT_USAGE_WIDTH
public static final int DEFAULT_USAGE_WIDTHConstant holding the default usage message width:80
.- See Also:
-
MINIMUM_USAGE_WIDTH
private static final int MINIMUM_USAGE_WIDTH- See Also:
-
DEFAULT_USAGE_LONG_OPTIONS_WIDTH
static final int DEFAULT_USAGE_LONG_OPTIONS_WIDTH- See Also:
-
DEFAULT_SYNOPSIS_INDENT
private static final int DEFAULT_SYNOPSIS_INDENT- See Also:
-
DEFAULT_SYNOPSIS_AUTO_INDENT_THRESHOLD
private static final double DEFAULT_SYNOPSIS_AUTO_INDENT_THRESHOLD- See Also:
-
MAX_SYNOPSIS_AUTO_INDENT_THRESHOLD
private static final double MAX_SYNOPSIS_AUTO_INDENT_THRESHOLD- See Also:
-
DEFAULT_USAGE_AUTO_WIDTH
Constant Boolean holding the default setting for whether to attempt to adjust the width to the terminal width:.
-
DEFAULT_SYNOPSIS_HEADING
Constant String holding the default synopsis heading:"Usage: "
.- See Also:
-
DEFAULT_SYNOPSIS_SUBCOMMANDS
Constant String holding the default synopsis subcommands:"[COMMAND]"
.- See Also:
-
DEFAULT_COMMAND_LIST_HEADING
Constant String holding the default command list heading:"Commands:%n"
.- See Also:
-
DEFAULT_REQUIRED_OPTION_MARKER
static final char DEFAULT_REQUIRED_OPTION_MARKERConstant String holding the default string that separates options from option parameters:' '
(' ').- See Also:
-
DEFAULT_ABBREVIATE_SYNOPSIS
Constant Boolean holding the default setting for whether to abbreviate the synopsis:.
-
DEFAULT_SORT_OPTIONS
Constant Boolean holding the default setting for whether to sort the options alphabetically:.
-
DEFAULT_SORT_SYNOPSIS
Constant Boolean holding the default setting for whether to sort options in the synopsis alphabetically:.
-
DEFAULT_SHOW_AT_FILE
Constant Boolean holding the default setting for whether to show an entry for @-files in the usage help message. -
DEFAULT_SHOW_END_OF_OPTIONS
Constant Boolean holding the default setting for whether to show an entry for the--
End of Options delimiter in the usage help message. -
DEFAULT_SHOW_DEFAULT_VALUES
Constant Boolean holding the default setting for whether to show default values in the usage help message:.
-
DEFAULT_HIDDEN
Constant Boolean holding the default setting for whether this command should be listed in the usage help of the parent command:.
-
DEFAULT_ADJUST_CJK
Constant Boolean holding the default setting for whether line breaks should take wide CJK characters into account:.
-
DEFAULT_SINGLE_VALUE
- See Also:
-
DEFAULT_MULTI_LINE
-
helpFactory
-
sectionKeys
-
helpSectionRendererMap
-
description
-
customSynopsis
-
header
-
abbreviateSynopsis
-
sortOptions
-
sortSynopsis
-
showDefaultValues
-
showAtFileInUsageHelp
-
showEndOfOptionsDelimiterInUsageHelp
-
autoWidth
-
requiredOptionMarker
-
headerHeading
-
synopsisHeading
-
synopsisSubcommandLabel
-
synopsisAutoIndentThreshold
-
synopsisIndent
-
descriptionHeading
-
parameterListHeading
-
optionListHeading
-
commandListHeading
-
exitCodeListHeading
-
exitCodeListStrings
-
exitCodeList
-
width
-
longOptionsMaxWidth
-
cachedTerminalWidth
-
interpolator
-
messages
-
adjustLineBreaksForWideCJKCharacters
-
-
Constructor Details
-
UsageMessageSpec
public UsageMessageSpec() -
UsageMessageSpec
UsageMessageSpec(CommandLine.Model.Interpolator interpolator)
-
-
Method Details
-
width
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 - Throws:
IllegalArgumentException
- if the specified width is less than 55
-
longOptionsMaxWidth
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
-
getSysPropertyWidthOrDefault
private int getSysPropertyWidthOrDefault(int defaultWidth, boolean detectTerminalSize) -
shouldDetectTerminalSize
private static boolean shouldDetectTerminalSize(boolean autoWidthEnabledInApplication) -
isNumeric
-
getTerminalWidth
private static int getTerminalWidth() -
detectTerminalWidth
private static int detectTerminalWidth() -
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 thewidth(int)
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"
toAUTO
, and may disable this by setting this system property to a numeric value. This feature requires Java 7 or greater. The default isfalse
.- Since:
- 4.0
- See Also:
-
autoWidth
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 isfalse
.- Parameters:
detectTerminalSize
- whether picocli should attempt to detect the terminal size- Since:
- 4.0
- See Also:
-
isCodePointCJK
static boolean isCodePointCJK(int codePoint) Given a codePoint, is this codePoint considered to be a CJK character? Shamelessly stolen from StackOverflow where it was contributed by user Rakesh N. (Upvote! :-) )- Parameters:
codePoint
- code point to test- Returns:
true
if the character is a CJK character
-
createHelpSectionRendererMap
Returns the help section renderers for the predefined section keys. see:sectionKeys()
-
sectionKeys
Returns the section keys in the order that the usage help message should render the sections. This ordering may be modified with thesectionKeys 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_AT_FILE_PARAMETER
SECTION_KEY_PARAMETER_LIST
SECTION_KEY_OPTION_LIST_HEADING
SECTION_KEY_OPTION_LIST
SECTION_KEY_END_OF_OPTIONS
SECTION_KEY_COMMAND_LIST_HEADING
SECTION_KEY_COMMAND_LIST
SECTION_KEY_EXIT_CODE_LIST_HEADING
SECTION_KEY_EXIT_CODE_LIST
SECTION_KEY_FOOTER_HEADING
SECTION_KEY_FOOTER
- Since:
- 3.9
-
sectionKeys
Sets the section keys in the order that the usage help message should render the sections.- Since:
- 3.9
- See Also:
-
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 thesectionKeys setter
. Sections that are either not in this map or not in the list returned bysectionKeys
are omitted.- Since:
- 3.9
- See Also:
-
sectionMap
public CommandLine.Model.UsageMessageSpec sectionMap(Map<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.- 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
Returns theIHelpFactory
that is used to construct the usage help message.- Since:
- 3.9
- See Also:
-
helpFactory
Sets a newIHelpFactory
to customize the usage help message.- Parameters:
helpFactory
- the new help factory. Must be non-null
.- Returns:
- this
UsageMessageSpec
object, to allow method chaining
-
interpolate
-
interpolate
-
str
-
arr
-
resourceStr
-
resourceArr
-
headerHeading
Returns the optional heading preceding the header section. Initialized fromCommandLine.Command.headerHeading()
, or""
(empty 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 fromCommandLine.Command.header()
if theCommand
annotation is present, otherwise this is an empty array and the help message has no header. Applications may programmatically set this field to create a custom help message. -
synopsisHeading
Returns the optional heading preceding the synopsis. Initialized fromCommandLine.Command.synopsisHeading()
,"Usage: "
by default. -
synopsisSubcommandLabel
Returns the String representing the subcommands in the synopsis. Initialized fromCommandLine.Command.synopsisSubcommandLabel()
,"[COMMANDS]"
by default.- Since:
- 4.0
-
synopsisAutoIndentThreshold
public double synopsisAutoIndentThreshold()Returns the fraction of the usage helpwidth()
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 is0.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 thesynopsisIndent()
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 thewidth()
times thesynopsisAutoIndentThreshold()
,-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
Returns the optional custom synopsis lines to use instead of the auto-generated synopsis. Initialized fromCommandLine.Command.customSynopsis()
if theCommand
annotation is present, otherwise this is an empty array and the synopsis is generated. Applications may programmatically set this field to create a custom help message. -
descriptionHeading
Returns the optional heading preceding the description section. Initialized fromCommandLine.Command.descriptionHeading()
, or null. -
description
Returns the optional text lines to use as the description of the help message, displayed between the synopsis and the options list. Initialized fromCommandLine.Command.description()
if theCommand
annotation is present, otherwise this is an empty array and the help message has no description. Applications may programmatically set this field to create a custom help message. -
parameterListHeading
Returns the optional heading preceding the parameter list. Initialized fromCommandLine.Command.parameterListHeading()
, or null. -
optionListHeading
Returns the optional heading preceding the options list. Initialized fromCommandLine.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.6
-
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:
-
commandListHeading
Returns the optional heading preceding the subcommand list. Initialized fromCommandLine.Command.commandListHeading()
."Commands:%n"
by default. -
exitCodeListHeading
Returns the optional heading preceding the exit codes section, may contain"%n"
line separators.""
(empty string) by default. -
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 thekeyValuesMap
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 registered.
- Since:
- 4.0
- See Also:
-
keyValuesMap
Creates and returns aMap
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
-
headerHeading
Sets the heading preceding the header section. Initialized fromCommandLine.Command.headerHeading()
, or null.- Returns:
- this UsageMessageSpec for method chaining
-
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
Sets the optional heading preceding the synopsis.- Returns:
- this UsageMessageSpec for method chaining
-
synopsisSubcommandLabel
Sets the String representing the subcommands in the synopsis.- Returns:
- this UsageMessageSpec for method chaining
- Since:
- 4.0
-
synopsisAutoIndentThreshold
Sets the fraction of the usage helpwidth()
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 is0.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 thesynopsisIndent()
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
- Throws:
IllegalArgumentException
- if the specified value is less than 0.0 or greater than 0.9- Since:
- 4.0
-
synopsisIndent
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 thesynopsisAutoIndentThreshold()
fraction of thewidth()
,-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
Sets whether the synopsis line(s) should show an abbreviated synopsis without detailed option names.- Returns:
- this UsageMessageSpec for method chaining
-
customSynopsis
Sets the optional custom synopsis lines to use instead of the auto-generated synopsis.- Returns:
- this UsageMessageSpec for method chaining
-
descriptionHeading
Sets the heading preceding the description section.- Returns:
- this UsageMessageSpec for method chaining
-
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
Sets the optional heading preceding the parameter list.- Returns:
- this UsageMessageSpec for method chaining
-
optionListHeading
Sets the heading preceding the options list.- Returns:
- this UsageMessageSpec for method chaining
-
sortOptions
Sets whether the options list in the usage help message should be sorted alphabetically.- Returns:
- this UsageMessageSpec for method chaining
-
sortSynopsis
Sets whether the options in the synopsis should be sorted alphabetically.- Returns:
- this UsageMessageSpec for method chaining
- Since:
- 4.7.6
-
requiredOptionMarker
Sets the character used to prefix required options in the options list.- Returns:
- this UsageMessageSpec for method chaining
-
showDefaultValues
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
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
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:
-
commandListHeading
Sets the optional heading preceding the subcommand list.- Returns:
- this UsageMessageSpec for method chaining
-
exitCodeListHeading
Sets the optional heading preceding the exit codes section, may contain"%n"
line separators.""
(empty string) by default.- Since:
- 4.0
-
exitCodeList
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:
-
messages
Returns the Messages for this usage help message specification, ornull
.- Returns:
- the Messages object that encapsulates this command's resource bundle
- Since:
- 3.6
-
messages
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 benull
- 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 CommandLine.Model.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
-
updateFromCommand
void updateFromCommand(CommandLine.Command cmd, CommandLine.Model.CommandSpec commandSpec, boolean loadResourceBundle) -
initFromMixin
void initFromMixin(CommandLine.Model.UsageMessageSpec mixin, CommandLine.Model.CommandSpec commandSpec) -
initFrom
void initFrom(CommandLine.Model.UsageMessageSpec settings, CommandLine.Model.CommandSpec commandSpec)
-