Class BuiltinHelpFormatter
- java.lang.Object
-
- joptsimple.BuiltinHelpFormatter
-
- All Implemented Interfaces:
HelpFormatter
public class BuiltinHelpFormatter extends java.lang.Object implements HelpFormatter
A help formatter that allows configuration of overall row width and column separator width.
The formatter produces output in two sections: one for the options, and one for non-option arguments.
The options section has two columns: the left column for the options, and the right column for their descriptions. The formatter will allow as much space as possible for the descriptions, by minimizing the option column's width, no greater than slightly less than half the overall desired width.
The non-option arguments section is one column, occupying as much width as it can.
Subclasses are free to override bits of this implementation as they see fit. Inspect the code carefully to understand the flow of control that this implementation guarantees.
-
-
Field Summary
Fields Modifier and Type Field Description private Rows
nonOptionRows
private Rows
optionRows
-
Constructor Summary
Constructors Constructor Description BuiltinHelpFormatter()
Makes a formatter with a pre-configured overall row width and column separator width.BuiltinHelpFormatter(int desiredOverallWidth, int desiredColumnSeparatorWidth)
Makes a formatter with a given overall row width and column separator width.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected void
addHeaders(java.util.Collection<? extends OptionDescriptor> options)
Adds help row headers for option help columns.protected void
addNonOptionRow(java.lang.String single)
Adds a single row of non-option argument help.protected void
addNonOptionsDescription(java.util.Collection<? extends OptionDescriptor> options)
Adds non-option arguments descriptions to the help output.protected void
addOptionRow(java.lang.String single)
Adds a row of option help output in the left column, with empty space in the right column.protected void
addOptionRow(java.lang.String left, java.lang.String right)
Adds a row of option help output in the left and right columns.protected void
addOptions(java.util.Collection<? extends OptionDescriptor> options)
Adds help rows for the given options.protected void
addRows(java.util.Collection<? extends OptionDescriptor> options)
Adds rows of help output for the given options.protected void
appendOptionHelp(java.lang.StringBuilder buffer, java.lang.String typeIndicator, java.lang.String description, boolean required)
Appends info about an option's argument to the given buffer.protected void
appendTypeIndicator(java.lang.StringBuilder buffer, java.lang.String typeIndicator, java.lang.String description, char start, char end)
Appends a type indicator for an option's argument to the given buffer.protected java.lang.String
createDefaultValuesDisplay(java.util.List<?> defaultValues)
Gives a display string for the default values of an option's argument.protected java.lang.String
createDescriptionDisplay(OptionDescriptor descriptor)
Gives a string representing a description of the option with the given descriptor.protected java.lang.String
createNonOptionArgumentsDisplay(OptionDescriptor nonOptionDescriptor)
Creates a non-options argument help string.protected java.lang.String
createOptionDisplay(OptionDescriptor descriptor)
Creates a string for how the given option descriptor is to be represented in help.protected java.lang.String
extractTypeIndicator(OptionDescriptor descriptor)
Gives an indicator of the type of arguments of the option described by the given descriptor, for use in help.protected OptionDescriptor
findAndRemoveNonOptionsSpec(java.util.Collection<? extends OptionDescriptor> 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.java.lang.String
format(java.util.Map<java.lang.String,? extends OptionDescriptor> options)
Produces help text, given a set of option descriptors.protected java.lang.String
formattedHelpOutput()
Produces help output for an entire set of options and non-option arguments.protected boolean
hasRequiredOption(java.util.Collection<? extends OptionDescriptor> options)
Tells whether the given option descriptors contain a "required" option.protected void
maybeAppendNonOptionsDescription(java.lang.StringBuilder buffer, OptionDescriptor nonOptions)
Appends help for the given non-option arguments descriptor to the given buffer.protected void
maybeAppendOptionInfo(java.lang.StringBuilder buffer, OptionDescriptor descriptor)
Appends additional info about the given option to the given buffer.protected java.lang.String
message(java.lang.String keySuffix, java.lang.Object... args)
Looks up and gives a resource bundle message.protected java.lang.String
nonOptionOutput()
Produces non-option argument help.protected java.lang.String
optionLeader(java.lang.String option)
Gives a string that represents the given option's "option leader" in help.protected java.lang.String
optionOutput()
Produces help for options and their descriptions.protected boolean
shouldShowNonOptionArgumentDisplay(OptionDescriptor nonOptionDescriptor)
Decides whether or not to show a non-option arguments help.
-
-
-
Constructor Detail
-
BuiltinHelpFormatter
BuiltinHelpFormatter()
Makes a formatter with a pre-configured overall row width and column separator width.
-
BuiltinHelpFormatter
public BuiltinHelpFormatter(int desiredOverallWidth, int desiredColumnSeparatorWidth)
Makes a formatter with a given overall row width and column separator width.- Parameters:
desiredOverallWidth
- how many characters wide to make the overall help displaydesiredColumnSeparatorWidth
- how many characters wide to make the separation between option column and description column
-
-
Method Detail
-
format
public java.lang.String format(java.util.Map<java.lang.String,? extends OptionDescriptor> options)
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()
- Specified by:
format
in interfaceHelpFormatter
- Parameters:
options
- descriptors for the configured options of a parser- Returns:
- text to be used as help
- See Also:
OptionParser.printHelpOn(java.io.Writer)
,OptionParser.formatHelpWith(HelpFormatter)
- Sorts the given descriptors by their first elements of
-
addOptionRow
protected void addOptionRow(java.lang.String single)
Adds a row of option help output in the left column, with empty space in the right column.- Parameters:
single
- text to put in the left column
-
addOptionRow
protected void addOptionRow(java.lang.String left, java.lang.String right)
Adds a row of option help output in the left and right columns.- Parameters:
left
- text to put in the left columnright
- text to put in the right column
-
addNonOptionRow
protected void addNonOptionRow(java.lang.String single)
Adds a single row of non-option argument help.- Parameters:
single
- single row of non-option argument help text
-
fitRowsToWidth
protected void fitRowsToWidth()
Resizes the columns of all the rows to be no wider than the widest element in that column.
-
nonOptionOutput
protected java.lang.String nonOptionOutput()
Produces non-option argument help.- Returns:
- non-option argument help
-
optionOutput
protected java.lang.String optionOutput()
Produces help for options and their descriptions.- Returns:
- option help
-
formattedHelpOutput
protected java.lang.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:
- help output for entire set of options and non-option arguments
- the result of
-
addRows
protected void addRows(java.util.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 byaddOptions(java.util.Collection)
with the options as the argument. - Calls
fitRowsToWidth()
.
- Parameters:
options
- descriptors for the configured options of a parser
- Calls
-
addNonOptionsDescription
protected void addNonOptionsDescription(java.util.Collection<? extends OptionDescriptor> options)
Adds non-option arguments descriptions to the help output.
This implementation:
- Parameters:
options
- descriptors for the configured options of a parser
-
shouldShowNonOptionArgumentDisplay
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 ofOptionDescriptor.description()
,OptionDescriptor.argumentTypeIndicator()
, orOptionDescriptor.argumentDescription()
.- Parameters:
nonOptionDescriptor
- non-option argument descriptor- Returns:
true
if non-options argument help should be shown
-
createNonOptionArgumentsDisplay
protected java.lang.String createNonOptionArgumentsDisplay(OptionDescriptor nonOptionDescriptor)
Creates a non-options argument help string.
This implementation creates an empty string buffer and calls
maybeAppendOptionInfo(StringBuilder, OptionDescriptor)
andmaybeAppendNonOptionsDescription(StringBuilder, OptionDescriptor)
, passing them the buffer and the non-option arguments descriptor.- Parameters:
nonOptionDescriptor
- non-option argument descriptor- Returns:
- help string for non-options
-
maybeAppendNonOptionsDescription
protected void maybeAppendNonOptionsDescription(java.lang.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 aOptionDescriptor.description()
; followed by theOptionDescriptor.description()
.- Parameters:
buffer
- string buffernonOptions
- non-option arguments descriptor
-
findAndRemoveNonOptionsSpec
protected OptionDescriptor findAndRemoveNonOptionsSpec(java.util.Collection<? extends OptionDescriptor> options)
Finds the non-option arguments descriptor in the given collection, removes it, and returns it.- Parameters:
options
- descriptors for the configured options of a parser- Returns:
- the non-option arguments descriptor
-
addHeaders
protected void addHeaders(java.util.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
- descriptors for the configured options of a parser
-
hasRequiredOption
protected final boolean hasRequiredOption(java.util.Collection<? extends OptionDescriptor> options)
Tells whether the given option descriptors contain a "required" option.- Parameters:
options
- descriptors for the configured options of a parser- Returns:
true
if at least one of the options is "required"
-
addOptions
protected void addOptions(java.util.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 ofcreateOptionDisplay(OptionDescriptor)
andcreateDescriptionDisplay(OptionDescriptor)
, respectively, as arguments.- Parameters:
options
- descriptors for the configured options of a parser
-
createOptionDisplay
protected java.lang.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
- a descriptor for a configured option of a parser- Returns:
- help string
-
optionLeader
protected java.lang.String optionLeader(java.lang.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
- a string option- Returns:
- an "option leader" string
-
maybeAppendOptionInfo
protected void maybeAppendOptionInfo(java.lang.StringBuilder buffer, OptionDescriptor descriptor)
Appends additional info about the given option to the given buffer.
This implementation:
- calls
extractTypeIndicator(OptionDescriptor)
for the descriptor - calls
OptionDescriptor.argumentDescription()
for the descriptor - if either of the above is present, calls
appendOptionHelp(StringBuilder, String, String, boolean)
- Parameters:
buffer
- string bufferdescriptor
- a descriptor for a configured option of a parser
- calls
-
extractTypeIndicator
protected java.lang.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
- a descriptor for a configured option of a parser- Returns:
- type indicator text
-
appendOptionHelp
protected void appendOptionHelp(java.lang.StringBuilder buffer, java.lang.String typeIndicator, java.lang.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 withrequired
arguments, and with the surrounding characters'['
and']'
for options with optional arguments.- Parameters:
buffer
- string buffertypeIndicator
- type indicatordescription
- type descriptionrequired
- indicator of "required"-ness of the argument of the option
-
appendTypeIndicator
protected void appendTypeIndicator(java.lang.StringBuilder buffer, java.lang.String typeIndicator, java.lang.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
- string buffertypeIndicator
- type indicatordescription
- type descriptionstart
- starting characterend
- ending character
-
createDescriptionDisplay
protected java.lang.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 ofcreateDefaultValuesDisplay(java.util.List)
, surrounded by parentheses
- the descriptor's
- Parameters:
descriptor
- a descriptor for a configured option of a parser- Returns:
- display text for the option's description
- Asks for the descriptor's
-
createDefaultValuesDisplay
protected java.lang.String createDefaultValuesDisplay(java.util.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 theObject.toString()
of the whole list.- Parameters:
defaultValues
- some default values for a given option's argument- Returns:
- a display string for those default values
-
message
protected java.lang.String message(java.lang.String keySuffix, java.lang.Object... args)
Looks up and gives a resource bundle message.
This implementation looks in the bundle
"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
- suffix to use when looking up the bundle messageargs
- arguments to fill in the message template with- Returns:
- a formatted localized message
-
-