public class BuiltinHelpFormatter extends 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.
Constructor and Description |
---|
BuiltinHelpFormatter(int desiredOverallWidth,
int desiredColumnSeparatorWidth)
Makes a formatter with a given overall row width and column separator width.
|
Modifier and Type | Method and Description |
---|---|
protected void |
addHeaders(Collection<? extends OptionDescriptor> options)
Adds help row headers for option help columns.
|
protected void |
addNonOptionRow(String single)
Adds a single row of non-option argument help.
|
protected void |
addNonOptionsDescription(Collection<? extends OptionDescriptor> options)
Adds non-option arguments descriptions to the help output.
|
protected void |
addOptionRow(String single)
Adds a row of option help output in the left column, with empty space in the right column.
|
protected void |
addOptionRow(String left,
String right)
Adds a row of option help output in the left and right columns.
|
protected void |
addOptions(Collection<? extends OptionDescriptor> options)
Adds help rows for the given options.
|
protected void |
addRows(Collection<? extends OptionDescriptor> options)
Adds rows of help output for the given options.
|
protected void |
appendOptionHelp(StringBuilder buffer,
String typeIndicator,
String description,
boolean required)
Appends info about an option's argument to the given buffer.
|
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.
|
protected String |
createDefaultValuesDisplay(List<?> defaultValues)
Gives a display string for the default values of an option's argument.
|
protected String |
createDescriptionDisplay(OptionDescriptor descriptor)
Gives a string representing a description of the option with the given descriptor.
|
protected String |
createNonOptionArgumentsDisplay(OptionDescriptor nonOptionDescriptor)
Creates a non-options argument help string.
|
protected String |
createOptionDisplay(OptionDescriptor descriptor)
Creates a string for how the given option descriptor is to be represented in help.
|
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.
|
protected OptionDescriptor |
findAndRemoveNonOptionsSpec(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.
|
String |
format(Map<String,? extends OptionDescriptor> options)
Produces help text, given a set of option descriptors.
|
protected String |
formattedHelpOutput()
Produces help output for an entire set of options and non-option arguments.
|
protected boolean |
hasRequiredOption(Collection<? extends OptionDescriptor> options)
Tells whether the given option descriptors contain a "required" option.
|
protected void |
maybeAppendNonOptionsDescription(StringBuilder buffer,
OptionDescriptor nonOptions)
Appends help for the given non-option arguments descriptor to the given buffer.
|
protected void |
maybeAppendOptionInfo(StringBuilder buffer,
OptionDescriptor descriptor)
Appends additional info about the given option to the given buffer.
|
protected String |
message(String keySuffix,
Object... args)
Looks up and gives a resource bundle message.
|
protected String |
nonOptionOutput()
Produces non-option argument help.
|
protected String |
optionLeader(String option)
Gives a string that represents the given option's "option leader" in help.
|
protected 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.
|
public BuiltinHelpFormatter(int desiredOverallWidth, int desiredColumnSeparatorWidth)
desiredOverallWidth
- how many characters wide to make the overall help displaydesiredColumnSeparatorWidth
- how many characters wide to make the separation between option column and
description columnpublic String format(Map<String,? extends OptionDescriptor> options)
This implementation:
OptionDescriptor.options()
addRows(java.util.Collection)
formattedHelpOutput()
format
in interface HelpFormatter
options
- descriptors for the configured options of a parserOptionParser.printHelpOn(java.io.Writer)
,
OptionParser.formatHelpWith(HelpFormatter)
protected void addOptionRow(String single)
single
- text to put in the left columnprotected void addOptionRow(String left, String right)
left
- text to put in the left columnright
- text to put in the right columnprotected void addNonOptionRow(String single)
single
- single row of non-option argument help textprotected void fitRowsToWidth()
protected String nonOptionOutput()
protected String optionOutput()
protected String formattedHelpOutput()
Produces help output for an entire set of options and non-option arguments.
This implementation concatenates:
nonOptionOutput()
optionOutput()
protected void addRows(Collection<? extends OptionDescriptor> options)
Adds rows of help output for the given options.
This implementation:
addNonOptionsDescription(java.util.Collection)
with the options as the argumentaddOptionRow(String)
with an argument that indicates
that no options are specified.addHeaders(java.util.Collection)
with the options as the argument,
followed by addOptions(java.util.Collection)
with the options as the argument.fitRowsToWidth()
.options
- descriptors for the configured options of a parserprotected void addNonOptionsDescription(Collection<? extends OptionDescriptor> options)
Adds non-option arguments descriptions to the help output.
This implementation:
options
- descriptors for the configured options of a parserprotected 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()
.
nonOptionDescriptor
- non-option argument descriptortrue
if non-options argument help should be shownprotected 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.
nonOptionDescriptor
- non-option argument descriptorprotected 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()
.
buffer
- string buffernonOptions
- non-option arguments descriptorprotected OptionDescriptor findAndRemoveNonOptionsSpec(Collection<? extends OptionDescriptor> options)
options
- descriptors for the configured options of a parserprotected 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 "-"
.
options
- descriptors for the configured options of a parserprotected final boolean hasRequiredOption(Collection<? extends OptionDescriptor> options)
options
- descriptors for the configured options of a parsertrue
if at least one of the options is "required"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.
options
- descriptors for the configured options of a parserprotected 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 ""
OptionDescriptor.options()
of the descriptor, separated by ", "
:
optionLeader(String)
of the optionmaybeAppendOptionInfo(StringBuilder, OptionDescriptor)
descriptor
- a descriptor for a configured option of a parserprotected 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 "-"
.
option
- a string optionprotected void maybeAppendOptionInfo(StringBuilder buffer, OptionDescriptor descriptor)
Appends additional info about the given option to the given buffer.
This implementation:
extractTypeIndicator(OptionDescriptor)
for the descriptorOptionDescriptor.argumentDescription()
for the descriptorappendOptionHelp(StringBuilder, String, String, boolean)
buffer
- string bufferdescriptor
- a descriptor for a configured option of a parserprotected 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"
.
descriptor
- a descriptor for a configured option of a parserprotected 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.
buffer
- string buffertypeIndicator
- type indicatordescription
- type descriptionrequired
- indicator of "required"-ness of the argument of the optionprotected 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
null
": "
plus the description if the type indicator is
present; otherwise the description onlyend
buffer
- string buffertypeIndicator
- type indicatordescription
- type descriptionstart
- starting characterend
- ending characterprotected String createDescriptionDisplay(OptionDescriptor descriptor)
Gives a string representing a description of the option with the given descriptor.
This implementation:
OptionDescriptor.defaultValues()
OptionDescriptor.description()
.OptionDescriptor.description()
' '
"default: "
plus the result of createDefaultValuesDisplay(java.util.List)
,
surrounded by parenthesesdescriptor
- a descriptor for a configured option of a parserprotected 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.
defaultValues
- some default values for a given option's argumentprotected String message(String keySuffix, 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.
keySuffix
- suffix to use when looking up the bundle messageargs
- arguments to fill in the message template withCopyright © 2016. All Rights Reserved.