Package joptsimple

Class BuiltinHelpFormatter

java.lang.Object
joptsimple.BuiltinHelpFormatter
All Implemented Interfaces:
HelpFormatter

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.

  • Field Details

    • nonOptionRows

      private final Rows nonOptionRows
    • optionRows

      private final Rows optionRows
  • Constructor Details

    • 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 display
      desiredColumnSeparatorWidth - how many characters wide to make the separation between option column and description column
  • Method Details

    • format

      public String format(Map<String,? extends OptionDescriptor> options)
      Produces help text, given a set of option descriptors.

      This implementation:

      Specified by:
      format in interface HelpFormatter
      Parameters:
      options - descriptors for the configured options of a parser
      Returns:
      text to be used as help
      See Also:
    • addOptionRow

      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 - text to put in the left column
    • addOptionRow

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

      protected void addNonOptionRow(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 String nonOptionOutput()
      Produces non-option argument help.
      Returns:
      non-option argument help
    • optionOutput

      protected String optionOutput()
      Produces help for options and their descriptions.
      Returns:
      option help
    • formattedHelpOutput

      protected String formattedHelpOutput()

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

      This implementation concatenates:

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

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

      Adds rows of help output for the given options.

      This implementation:

      Parameters:
      options - descriptors for the configured options of a parser
    • addNonOptionsDescription

      protected void addNonOptionsDescription(Collection<? extends OptionDescriptor> options)
      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 of OptionDescriptor.description(), OptionDescriptor.argumentTypeIndicator(), or OptionDescriptor.argumentDescription().

      Parameters:
      nonOptionDescriptor - non-option argument descriptor
      Returns:
      true if non-options argument help should be shown
    • createNonOptionArgumentsDisplay

      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 - non-option argument descriptor
      Returns:
      help string for non-options
    • maybeAppendNonOptionsDescription

      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 - string buffer
      nonOptions - non-option arguments descriptor
    • findAndRemoveNonOptionsSpec

      protected OptionDescriptor findAndRemoveNonOptionsSpec(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(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(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(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 - descriptors for the configured options of a parser
    • createOptionDisplay

      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:

      Parameters:
      descriptor - a descriptor for a configured option of a parser
      Returns:
      help string
    • optionLeader

      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 - a string option
      Returns:
      an "option leader" string
    • maybeAppendOptionInfo

      protected void maybeAppendOptionInfo(StringBuilder buffer, OptionDescriptor descriptor)

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

      This implementation:

      Parameters:
      buffer - string buffer
      descriptor - a descriptor for a configured option of a parser
    • extractTypeIndicator

      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 - a descriptor for a configured option of a parser
      Returns:
      type indicator text
    • appendOptionHelp

      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 - string buffer
      typeIndicator - type indicator
      description - type description
      required - indicator of "required"-ness of the argument of the option
    • appendTypeIndicator

      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 - string buffer
      typeIndicator - type indicator
      description - type description
      start - starting character
      end - ending character
    • createDescriptionDisplay

      protected String createDescriptionDisplay(OptionDescriptor descriptor)

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

      This implementation:

      Parameters:
      descriptor - a descriptor for a configured option of a parser
      Returns:
      display text for the option's description
    • createDefaultValuesDisplay

      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 - some default values for a given option's argument
      Returns:
      a display string for those default values
    • message

      protected 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.

      Parameters:
      keySuffix - suffix to use when looking up the bundle message
      args - arguments to fill in the message template with
      Returns:
      a formatted localized message