OpenJDK 27 · jdk.internal.joptsimple.BuiltinHelpFormatter

Modifier and Type	Field and Description
private final Rows	nonOptionRows
private final Rows	optionRows

Access	Constructor and Description
pack-priv	BuiltinHelpFormatter() Makes a formatter with a pre-configured overall row width and column separator width.
public	BuiltinHelpFormatter(int how many characters wide to make the overall help display desiredOverallWidth, int how many characters wide to make the separation between option column and description column desiredColumnSeparatorWidth) Makes a formatter with a given overall row width and column separator width.

Method Summary

Modifier and Type	Method and Description
protected void	addHeaders(Collection<? extends OptionDescriptor> descriptors for the configured options of a parser options) Adds help row headers for option help columns.
protected void	addNonOptionRow(String single row of non-option argument help text single) Adds a single row of non-option argument help.
protected void	addNonOptionsDescription(Collection<? extends OptionDescriptor> descriptors for the configured options of a parser options) Adds non-option arguments descriptions to the help output.
protected void	addOptionRow(String text to put in the left column single) Adds a row of option help output in the left column, with empty space in the right column.
protected void	addOptionRow(String text to put in the left column left, String text to put in the right column right) Adds a row of option help output in the left and right columns.
protected void	addOptions(Collection<? extends OptionDescriptor> descriptors for the configured options of a parser options) Adds help rows for the given options.
protected void	addRows(Collection<? extends OptionDescriptor> descriptors for the configured options of a parser options) Adds rows of help output for the given options.
protected void	appendOptionHelp(StringBuilder string buffer buffer, String type indicator typeIndicator, String type description description, boolean indicator of "required"-ness of the argument of the option required) Appends info about an option's argument to the given buffer.
protected void	appendTypeIndicator(StringBuilder string buffer buffer, String type indicator typeIndicator, String type description description, char starting character start, char ending character end) Appends a type indicator for an option's argument to the given buffer.
protected String	Returns: a display string for those default values createDefaultValuesDisplay(List<?> some default values for a given option's argument defaultValues) Gives a display string for the default values of an option's argument.
protected String	Returns: display text for the option's description createDescriptionDisplay(OptionDescriptor a descriptor for a configured option of a parser descriptor) Gives a string representing a description of the option with the given descriptor.
protected String	Returns: help string for non-options createNonOptionArgumentsDisplay(OptionDescriptor non-option argument descriptor nonOptionDescriptor) Creates a non-options argument help string.
protected String	Returns: help string createOptionDisplay(OptionDescriptor a descriptor for a configured option of a parser descriptor) Creates a string for how the given option descriptor is to be represented in help.
protected String	Returns: type indicator text extractTypeIndicator(OptionDescriptor a descriptor for a configured option of a parser descriptor) Gives an indicator of the type of arguments of the option described by the given descriptor, for use in help.
protected OptionDescriptor	Returns: the non-option arguments descriptor findAndRemoveNonOptionsSpec(Collection<? extends OptionDescriptor> descriptors for the configured options of a parser options) Finds the non-option arguments descriptor in the given collection, removes it, and returns it.
protected void	fitRowsToWidth() Resizes the columns of all the rows to be no wider than the widest element in that column.
public String	format(Map<String, ? extends OptionDescriptor> options) Implements jdk.internal.joptsimple.HelpFormatter.format. Produces help text, given a set of option descriptors.
protected String	Returns: help output for entire set of options and non-option arguments formattedHelpOutput() Produces help output for an entire set of options and non-option arguments.
protected final boolean	Returns: `true` if at least one of the options is "required" hasRequiredOption(Collection<? extends OptionDescriptor> descriptors for the configured options of a parser options) Tells whether the given option descriptors contain a "required" option.
protected void	maybeAppendNonOptionsDescription(StringBuilder string buffer buffer, OptionDescriptor non-option arguments descriptor nonOptions) Appends help for the given non-option arguments descriptor to the given buffer.
protected void	maybeAppendOptionInfo(StringBuilder string buffer buffer, OptionDescriptor a descriptor for a configured option of a parser descriptor) Appends additional info about the given option to the given buffer.
protected String	Returns: a formatted localized message message(String suffix to use when looking up the bundle message keySuffix, Object... arguments to fill in the message template with args) Looks up and gives a resource bundle message.
protected String	Returns: non-option argument help nonOptionOutput() Produces non-option argument help.
protected String	Returns: an "option leader" string optionLeader(String a string option option) Gives a string that represents the given option's "option leader" in help.
protected String	Returns: option help optionOutput() Produces help for options and their descriptions.
protected boolean	Returns: `true` if non-options argument help should be shown shouldShowNonOptionArgumentDisplay(OptionDescriptor non-option argument descriptor nonOptionDescriptor) Decides whether or not to show a non-option arguments help.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

nonOptionRows	back to summary
private final Rows nonOptionRows

optionRows	back to summary
private final Rows optionRows

BuiltinHelpFormatter	back to summary
pack-priv BuiltinHelpFormatter() Makes a formatter with a pre-configured overall row width and column separator width.

BuiltinHelpFormatter	back to summary
public BuiltinHelpFormatter(int desiredOverallWidth, int desiredColumnSeparatorWidth) Makes a formatter with a given overall row width and column separator width. Parameters desiredOverallWidth:int how many characters wide to make the overall help display desiredColumnSeparatorWidth:int how many characters wide to make the separation between option column and description column

Method Detail

addHeaders back to summary

addHeaders	back to summary
protected void addHeaders(Collection<? extends OptionDescriptor> options) Adds help row headers for option help columns. This implementation uses the headers `"Option"` and `"Description"`. If the options contain a "required" option, the `"Option"` header looks like `"Option (* = required)`. Both headers are "underlined" using `"-"`. Parameters options:Collection<? extends OptionDescriptor> descriptors for the configured options of a parser

protected void addHeaders(Collection<? extends OptionDescriptor> options)

Adds help row headers for option help columns.

This implementation uses the headers "Option" and "Description". If the options contain a "required" option, the "Option" header looks like "Option (* = required). Both headers are "underlined" using "-".

Parameters

options:Collection<? extends OptionDescriptor>: descriptors for the configured options of a parser

addNonOptionRow	back to summary
protected void addNonOptionRow(String single) Adds a single row of non-option argument help. Parameters single:String single row of non-option argument help text

addNonOptionRow

back to summary

protected void addNonOptionRow(String single)

Adds a single row of non-option argument help.

Parameters

single:String: single row of non-option argument help text

addNonOptionsDescription	back to summary
protected void addNonOptionsDescription(Collection<? extends OptionDescriptor> options) Adds non-option arguments descriptions to the help output. This implementation: Finds and removes the non-option arguments descriptor Decides whether there is anything to show for non-option arguments If there is, adds a header row and adds a non-option arguments description Parameters options:Collection<? extends OptionDescriptor> descriptors for the configured options of a parser

addNonOptionsDescription

back to summary

protected void addNonOptionsDescription(Collection<? extends OptionDescriptor> options)

Adds non-option arguments descriptions to the help output.

This implementation:

Parameters

options:Collection<? extends OptionDescriptor>: descriptors for the configured options of a parser

addOptionRow	back to summary
protected void addOptionRow(String single) Adds a row of option help output in the left column, with empty space in the right column. Parameters single:String text to put in the left column

addOptionRow

back to summary

protected void addOptionRow(String single)

Adds a row of option help output in the left column, with empty space in the right column.

Parameters

single:String: text to put in the left column

addOptionRow	back to summary
protected void addOptionRow(String left, String right) Adds a row of option help output in the left and right columns. Parameters left:String text to put in the left column right:String text to put in the right column

addOptionRow

back to summary

protected void addOptionRow(String left, String right)

Adds a row of option help output in the left and right columns.

Parameters

left:String: text to put in the left column
right:String: text to put in the right column

addOptions back to summary

addOptions	back to summary
protected void addOptions(Collection<? extends OptionDescriptor> options) Adds help rows for the given options. This implementation loops over the given options, and for each, calls `addOptionRow(String, String)` using the results of `createOptionDisplay(OptionDescriptor)` and `createDescriptionDisplay(OptionDescriptor)`, respectively, as arguments. Parameters options:Collection<? extends OptionDescriptor> descriptors for the configured options of a parser

protected void addOptions(Collection<? extends OptionDescriptor> options)

Adds help rows for the given options.

This implementation loops over the given options, and for each, calls addOptionRow(String, String) using the results of createOptionDisplay(OptionDescriptor) and createDescriptionDisplay(OptionDescriptor), respectively, as arguments.

Parameters

options:Collection<? extends OptionDescriptor>: descriptors for the configured options of a parser

addRows back to summary

addRows	back to summary
protected void addRows(Collection<? extends OptionDescriptor> options) Adds rows of help output for the given options. This implementation: Calls `addNonOptionsDescription(java.util.Collection)` with the options as the argument If there are no options, calls `addOptionRow(String)` with an argument that indicates that no options are specified. Otherwise, calls `addHeaders(java.util.Collection)` with the options as the argument, followed by `addOptions(java.util.Collection)` with the options as the argument. Calls `fitRowsToWidth()`. Parameters options:Collection<? extends OptionDescriptor> descriptors for the configured options of a parser

protected void addRows(Collection<? extends OptionDescriptor> options)

Adds rows of help output for the given options.

This implementation:

Calls addNonOptionsDescription(java.util.Collection) with the options as the argument
If there are no options, calls addOptionRow(String) with an argument that indicates that no options are specified.
Otherwise, calls addHeaders(java.util.Collection) with the options as the argument, followed by addOptions(java.util.Collection) with the options as the argument.
Calls fitRowsToWidth().

Parameters

options:Collection<? extends OptionDescriptor>: descriptors for the configured options of a parser

appendOptionHelp back to summary

appendOptionHelp	back to summary
protected void appendOptionHelp(StringBuilder buffer, String typeIndicator, String description, boolean required) Appends info about an option's argument to the given buffer. This implementation calls `appendTypeIndicator(StringBuilder, String, String, char, char)` with the surrounding characters `'<'` and `'>'` for options with `required` arguments, and with the surrounding characters `'['` and `']'` for options with optional arguments. Parameters buffer:StringBuilder string buffer typeIndicator:String type indicator description:String type description required:boolean indicator of "required"-ness of the argument of the option

protected void appendOptionHelp(StringBuilder buffer, String typeIndicator, String description, boolean required)

Appends info about an option's argument to the given buffer.

This implementation calls appendTypeIndicator(StringBuilder, String, String, char, char) with the surrounding characters '<' and '>' for options with required arguments, and with the surrounding characters '[' and ']' for options with optional arguments.

Parameters

buffer:StringBuilder: string buffer
typeIndicator:String: type indicator
description:String: type description
required:boolean: indicator of "required"-ness of the argument of the option

appendTypeIndicator back to summary

appendTypeIndicator	back to summary
protected void appendTypeIndicator(StringBuilder buffer, String typeIndicator, String description, char start, char end) Appends a type indicator for an option's argument to the given buffer. This implementation appends, in order: `' '` `start` the type indicator, if not `null` if the description is present, then `": "` plus the description if the type indicator is present; otherwise the description only `end` Parameters buffer:StringBuilder string buffer typeIndicator:String type indicator description:String type description start:char starting character end:char ending character

protected void appendTypeIndicator(StringBuilder buffer, String typeIndicator, String description, char start, char end)

Appends a type indicator for an option's argument to the given buffer.

This implementation appends, in order:

' '
start
the type indicator, if not null
if the description is present, then ": " plus the description if the type indicator is present; otherwise the description only
end

Parameters

buffer:StringBuilder: string buffer
typeIndicator:String: type indicator
description:String: type description
start:char: starting character
end:char: ending character

createDefaultValuesDisplay back to summary

createDefaultValuesDisplay	back to summary
protected String createDefaultValuesDisplay(List<?> defaultValues) Gives a display string for the default values of an option's argument. This implementation gives the `Object#toString()` of the first value if there is only one value, otherwise gives the `Object#toString()` of the whole list. Parameters defaultValues:List<?> some default values for a given option's argument Returns:String a display string for those default values

protected String createDefaultValuesDisplay(List<?> defaultValues)

Gives a display string for the default values of an option's argument.

This implementation gives the Object#toString() of the first value if there is only one value, otherwise gives the Object#toString() of the whole list.

Parameters

defaultValues:List<?>: some default values for a given option's argument

Returns:String

a display string for those default values

createDescriptionDisplay back to summary

createDescriptionDisplay	back to summary
protected String createDescriptionDisplay(OptionDescriptor descriptor) Gives a string representing a description of the option with the given descriptor. This implementation: Asks for the descriptor's `OptionDescriptor#defaultValues()` If they're not present, answers the descriptor's `OptionDescriptor#description()`. If they are present, concatenates and returns: the descriptor's `OptionDescriptor#description()` `' '` `"default: "` plus the result of `createDefaultValuesDisplay(java.util.List)`, surrounded by parentheses Parameters descriptor:OptionDescriptor a descriptor for a configured option of a parser Returns:String display text for the option's description

protected String createDescriptionDisplay(OptionDescriptor descriptor)

Gives a string representing a description of the option with the given descriptor.

This implementation:

Asks for the descriptor's OptionDescriptor#defaultValues()
If they're not present, answers the descriptor's OptionDescriptor#description().
If they are present, concatenates and returns:
- the descriptor's OptionDescriptor#description()
- ' '
- "default: " plus the result of createDefaultValuesDisplay(java.util.List), surrounded by parentheses

Parameters

descriptor:OptionDescriptor: a descriptor for a configured option of a parser

Returns:String

display text for the option's description

createNonOptionArgumentsDisplay back to summary

createNonOptionArgumentsDisplay	back to summary
protected String createNonOptionArgumentsDisplay(OptionDescriptor nonOptionDescriptor) Creates a non-options argument help string. This implementation creates an empty string buffer and calls `maybeAppendOptionInfo(StringBuilder, OptionDescriptor)` and `maybeAppendNonOptionsDescription(StringBuilder, OptionDescriptor)`, passing them the buffer and the non-option arguments descriptor. Parameters nonOptionDescriptor:OptionDescriptor non-option argument descriptor Returns:String help string for non-options

protected String createNonOptionArgumentsDisplay(OptionDescriptor nonOptionDescriptor)

Creates a non-options argument help string.

This implementation creates an empty string buffer and calls maybeAppendOptionInfo(StringBuilder, OptionDescriptor) and maybeAppendNonOptionsDescription(StringBuilder, OptionDescriptor), passing them the buffer and the non-option arguments descriptor.

Parameters

nonOptionDescriptor:OptionDescriptor: non-option argument descriptor

Returns:String

help string for non-options

createOptionDisplay back to summary

createOptionDisplay	back to summary
protected String createOptionDisplay(OptionDescriptor descriptor) Creates a string for how the given option descriptor is to be represented in help. This implementation gives a string consisting of the concatenation of: `"* "` for "required" options, otherwise `""` For each of the `OptionDescriptor#options()` of the descriptor, separated by `", "`: `optionLeader(String)` of the option the option the result of `maybeAppendOptionInfo(StringBuilder, OptionDescriptor)` Parameters descriptor:OptionDescriptor a descriptor for a configured option of a parser Returns:String help string

protected String createOptionDisplay(OptionDescriptor descriptor)

Creates a string for how the given option descriptor is to be represented in help.

This implementation gives a string consisting of the concatenation of:

"* " for "required" options, otherwise ""
For each of the OptionDescriptor#options() of the descriptor, separated by ", ":
- optionLeader(String) of the option
- the option
the result of maybeAppendOptionInfo(StringBuilder, OptionDescriptor)

Parameters

descriptor:OptionDescriptor: a descriptor for a configured option of a parser

Returns:String

help string

extractTypeIndicator back to summary

extractTypeIndicator	back to summary
protected String extractTypeIndicator(OptionDescriptor descriptor) Gives an indicator of the type of arguments of the option described by the given descriptor, for use in help. This implementation asks for the `OptionDescriptor#argumentTypeIndicator()` of the given descriptor, and if it is present and not `"java.lang.String"`, parses it as a fully qualified class name and returns the base name of that class; otherwise returns `"String"`. Parameters descriptor:OptionDescriptor a descriptor for a configured option of a parser Returns:String type indicator text

protected String extractTypeIndicator(OptionDescriptor descriptor)

Gives an indicator of the type of arguments of the option described by the given descriptor, for use in help.

This implementation asks for the OptionDescriptor#argumentTypeIndicator() of the given descriptor, and if it is present and not "java.lang.String", parses it as a fully qualified class name and returns the base name of that class; otherwise returns "String".

Parameters

descriptor:OptionDescriptor: a descriptor for a configured option of a parser

Returns:String

type indicator text

findAndRemoveNonOptionsSpec	back to summary
protected OptionDescriptor findAndRemoveNonOptionsSpec(Collection<? extends OptionDescriptor> options) Finds the non-option arguments descriptor in the given collection, removes it, and returns it. Parameters options:Collection<? extends OptionDescriptor> descriptors for the configured options of a parser Returns:OptionDescriptor the non-option arguments descriptor

findAndRemoveNonOptionsSpec

back to summary

protected OptionDescriptor findAndRemoveNonOptionsSpec(Collection<? extends OptionDescriptor> options)

Finds the non-option arguments descriptor in the given collection, removes it, and returns it.

Parameters

options:Collection<? extends OptionDescriptor>: descriptors for the configured options of a parser

Returns:OptionDescriptor

the non-option arguments descriptor

fitRowsToWidth	back to summary
protected void fitRowsToWidth() Resizes the columns of all the rows to be no wider than the widest element in that column.

format back to summary

format	back to summary
public String format(Map<String, ? extends OptionDescriptor> options) Implements jdk.internal.joptsimple.HelpFormatter.format. Doc from jdk.internal.joptsimple.HelpFormatter.format. Produces help text, given a set of option descriptors. This implementation: Sorts the given descriptors by their first elements of `OptionDescriptor#options()` Passes the resulting sorted set to `addRows(java.util.Collection)` Returns the result of `formattedHelpOutput()`

public String format(Map<String, ? extends OptionDescriptor> options)

Implements jdk.internal.joptsimple.HelpFormatter.format.

Doc from jdk.internal.joptsimple.HelpFormatter.format.

Produces help text, given a set of option descriptors.

This implementation:

Sorts the given descriptors by their first elements of OptionDescriptor#options()
Passes the resulting sorted set to addRows(java.util.Collection)
Returns the result of formattedHelpOutput()

formattedHelpOutput back to summary

formattedHelpOutput	back to summary
protected String formattedHelpOutput() Produces help output for an entire set of options and non-option arguments. This implementation concatenates: the result of `nonOptionOutput()` if there is non-option output, a line separator the result of `optionOutput()` Returns:String help output for entire set of options and non-option arguments

protected String formattedHelpOutput()

Produces help output for an entire set of options and non-option arguments.

This implementation concatenates:

the result of nonOptionOutput()
if there is non-option output, a line separator
the result of optionOutput()

Returns:String: help output for entire set of options and non-option arguments

hasRequiredOption back to summary

hasRequiredOption	back to summary
protected final boolean hasRequiredOption(Collection<? extends OptionDescriptor> options) Tells whether the given option descriptors contain a "required" option. Parameters options:Collection<? extends OptionDescriptor> descriptors for the configured options of a parser Returns:boolean `true` if at least one of the options is "required"

protected final boolean hasRequiredOption(Collection<? extends OptionDescriptor> options)

Tells whether the given option descriptors contain a "required" option.

Parameters

options:Collection<? extends OptionDescriptor>: descriptors for the configured options of a parser

Returns:boolean

true if at least one of the options is "required"

maybeAppendNonOptionsDescription back to summary

maybeAppendNonOptionsDescription	back to summary
protected void maybeAppendNonOptionsDescription(StringBuilder buffer, OptionDescriptor nonOptions) Appends help for the given non-option arguments descriptor to the given buffer. This implementation appends `" -- "` if the buffer has text in it and the non-option arguments descriptor has a `OptionDescriptor#description()`; followed by the `OptionDescriptor#description()`. Parameters buffer:StringBuilder string buffer nonOptions:OptionDescriptor non-option arguments descriptor

protected void maybeAppendNonOptionsDescription(StringBuilder buffer, OptionDescriptor nonOptions)

Appends help for the given non-option arguments descriptor to the given buffer.

This implementation appends " -- " if the buffer has text in it and the non-option arguments descriptor has a OptionDescriptor#description(); followed by the OptionDescriptor#description().

Parameters

buffer:StringBuilder: string buffer
nonOptions:OptionDescriptor: non-option arguments descriptor

maybeAppendOptionInfo back to summary

maybeAppendOptionInfo	back to summary
protected void maybeAppendOptionInfo(StringBuilder buffer, OptionDescriptor descriptor) Appends additional info about the given option to the given buffer. This implementation: calls `extractTypeIndicator(OptionDescriptor)` for the descriptor calls `jdk.internal.joptsimple.OptionDescriptor#argumentDescription()` for the descriptor if either of the above is present, calls `appendOptionHelp(StringBuilder, String, String, boolean)` Parameters buffer:StringBuilder string buffer descriptor:OptionDescriptor a descriptor for a configured option of a parser

protected void maybeAppendOptionInfo(StringBuilder buffer, OptionDescriptor descriptor)

Appends additional info about the given option to the given buffer.

This implementation:

calls extractTypeIndicator(OptionDescriptor) for the descriptor
calls jdk.internal.joptsimple.OptionDescriptor#argumentDescription() for the descriptor
if either of the above is present, calls appendOptionHelp(StringBuilder, String, String, boolean)

Parameters

buffer:StringBuilder: string buffer
descriptor:OptionDescriptor: a descriptor for a configured option of a parser

message back to summary

message	back to summary
protected String message(String keySuffix, Object... args) Looks up and gives a resource bundle message. This implementation looks in the bundle `"jdk.internal.joptsimple.HelpFormatterMessages"` in the default locale, using a key that is the concatenation of this class's fully qualified name, `'.'`, and the given key suffix, formats the corresponding value using the given arguments, and returns the result. Parameters keySuffix:String suffix to use when looking up the bundle message args:Object[] arguments to fill in the message template with Returns:String a formatted localized message

protected String message(String keySuffix, Object... args)

Looks up and gives a resource bundle message.

This implementation looks in the bundle "jdk.internal.joptsimple.HelpFormatterMessages" in the default locale, using a key that is the concatenation of this class's fully qualified name, '.', and the given key suffix, formats the corresponding value using the given arguments, and returns the result.

Parameters

keySuffix:String: suffix to use when looking up the bundle message
args:Object[]: arguments to fill in the message template with

Returns:String

a formatted localized message

nonOptionOutput	back to summary
protected String nonOptionOutput() Produces non-option argument help. Returns:String non-option argument help

nonOptionOutput

back to summary

protected String nonOptionOutput()

Produces non-option argument help.

Returns:String: non-option argument help

optionLeader back to summary

optionLeader	back to summary
protected String optionLeader(String option) Gives a string that represents the given option's "option leader" in help. This implementation answers with `"--"` for options of length greater than one; otherwise answers with `"-"`. Parameters option:String a string option Returns:String an "option leader" string

protected String optionLeader(String option)

Gives a string that represents the given option's "option leader" in help.

This implementation answers with "--" for options of length greater than one; otherwise answers with "-".

Parameters

option:String: a string option

Returns:String

an "option leader" string

optionOutput	back to summary
protected String optionOutput() Produces help for options and their descriptions. Returns:String option help

optionOutput

back to summary

protected String optionOutput()

Produces help for options and their descriptions.

Returns:String: option help

shouldShowNonOptionArgumentDisplay back to summary

shouldShowNonOptionArgumentDisplay	back to summary
protected boolean shouldShowNonOptionArgumentDisplay(OptionDescriptor nonOptionDescriptor) Decides whether or not to show a non-option arguments help. This implementation responds with `true` if the non-option descriptor has a non-`null`, non-empty value for any of `OptionDescriptor#description()`, `OptionDescriptor#argumentTypeIndicator()`, or `OptionDescriptor#argumentDescription()`. Parameters nonOptionDescriptor:OptionDescriptor non-option argument descriptor Returns:boolean `true` if non-options argument help should be shown

protected boolean shouldShowNonOptionArgumentDisplay(OptionDescriptor nonOptionDescriptor)

Decides whether or not to show a non-option arguments help.

This implementation responds with true if the non-option descriptor has a non-null, non-empty value for any of OptionDescriptor#description(), OptionDescriptor#argumentTypeIndicator(), or OptionDescriptor#argumentDescription().

Parameters

nonOptionDescriptor:OptionDescriptor: non-option argument descriptor

Returns:boolean

true if non-options argument help should be shown

public Class BuiltinHelpFormatter

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail