Package org.apache.commons.cli

Class HelpFormatter

java.lang.Object
org.apache.commons.cli.HelpFormatter
public class HelpFormatter extends Object
A formatter of help messages for command line options.

Example: 

 Options options = new Options();
 options.addOption(OptionBuilder.withLongOpt("file").withDescription("The file to be processed").hasArg().withArgName("FILE").isRequired().create('f'));
 options.addOption(OptionBuilder.withLongOpt("version").withDescription("Print the version of the application").create('v'));
 options.addOption(OptionBuilder.withLongOpt("help").create('h'));

 String header = "Do something useful with an input file\n\n";
 String footer = "\nPlease report issues at https://example.com/issues";

 HelpFormatter formatter = new HelpFormatter();
 formatter.printHelp("myapp", header, options, footer, true);

This produces the following output: 

 usage: myapp -f <FILE> [-h] [-v]
 Do something useful with an input file

  -f,--file <FILE>   The file to be processed
  -h,--help
  -v,--version       Print the version of the application

 Please report issues at https://example.com/issues

  • Field Details

    • HEADER_OPTIONS

      private static final String HEADER_OPTIONS
      "Options" text for options header
      See Also:

    • HEADER_SINCE

      private static final String HEADER_SINCE
      "Since" text for options header
      See Also:

    • HEADER_DESCRIPTION

      private static final String HEADER_DESCRIPTION
      "Description" test for options header
      See Also:

    • DEFAULT_WIDTH

      public static final int DEFAULT_WIDTH
      Default number of characters per line
      See Also:

    • DEFAULT_LEFT_PAD

      public static final int DEFAULT_LEFT_PAD
      Default padding to the left of each line
      See Also:

    • DEFAULT_DESC_PAD

      public static final int DEFAULT_DESC_PAD
      Number of space characters to be prefixed to each description line
      See Also:

    • DEFAULT_SYNTAX_PREFIX

      public static final String DEFAULT_SYNTAX_PREFIX
      The string to display at the beginning of the usage statement
      See Also:

    • DEFAULT_OPT_PREFIX

      public static final String DEFAULT_OPT_PREFIX
      Default prefix for shortOpts
      See Also:

    • DEFAULT_LONG_OPT_PREFIX

      public static final String DEFAULT_LONG_OPT_PREFIX
      Default prefix for long Option
      See Also:

    • DEFAULT_LONG_OPT_SEPARATOR

      public static final String DEFAULT_LONG_OPT_SEPARATOR
      Default separator displayed between a long Option and its value
      Since:
      1.3
      See Also:

    • DEFAULT_ARG_NAME

      public static final String DEFAULT_ARG_NAME
      Default name for an argument
      See Also:

    • defaultWidth

      @Deprecated public int defaultWidth
      Deprecated.
      Scope will be made private for next major version - use get/setWidth methods instead.
      Number of characters per line

    • defaultLeftPad

      @Deprecated public int defaultLeftPad
      Deprecated.
      Scope will be made private for next major version - use get/setLeftPadding methods instead.
      Amount of padding to the left of each line

    • defaultDescPad

      @Deprecated public int defaultDescPad
      Deprecated.
      Scope will be made private for next major version - use get/setDescPadding methods instead.
      The number of characters of padding to be prefixed to each description line

    • defaultSyntaxPrefix

      @Deprecated public String defaultSyntaxPrefix
      Deprecated.
      Scope will be made private for next major version - use get/setSyntaxPrefix methods instead.
      The string to display at the beginning of the usage statement

    • defaultNewLine

      @Deprecated public String defaultNewLine
      Deprecated.
      Scope will be made private for next major version - use get/setNewLine methods instead.
      The new line string

    • defaultOptPrefix

      @Deprecated public String defaultOptPrefix
      Deprecated.
      Scope will be made private for next major version - use get/setOptPrefix methods instead.
      The shortOpt prefix

    • defaultLongOptPrefix

      @Deprecated public String defaultLongOptPrefix
      Deprecated.
      Scope will be made private for next major version - use get/setLongOptPrefix methods instead.
      The long Opt prefix

    • defaultArgName

      @Deprecated public String defaultArgName
      Deprecated.
      Scope will be made private for next major version - use get/setArgName methods instead.
      The name of the argument

    • optionComparator

      protected Comparator<Option> optionComparator
      Comparator used to sort the options when they output in help text Defaults to case-insensitive alphabetical sorting by option key

    • deprecatedFormatFunction

      private final Function<Option,String> deprecatedFormatFunction
      Function to format the description for a deprecated option.

    • printWriter

      private final PrintWriter printWriter
      Where to print help.

    • showSince

      private final boolean showSince
      Flag to determine if since field should be displayed

    • longOptSeparator

      private String longOptSeparator
      The separator displayed between the long option and its value.

  • Constructor Details

    • HelpFormatter

      public HelpFormatter()
      Constructs a new instance.

    • HelpFormatter

      private HelpFormatter(Function<Option,String> deprecatedFormatFunction, PrintWriter printWriter, boolean showSince)
      Constructs a new instance.
      Parameters:
      printWriter - TODO

  • Method Details

    • builder

      public static HelpFormatter.Builder builder()
      Creates a new builder.
      Returns:
      a new builder.
      Since:
      1.7.0

    • createDefaultPrintWriter

      private static PrintWriter createDefaultPrintWriter()

    • getDescription

      public static String getDescription(Option option)
      Gets the option description or an empty string if the description is null.
      Parameters:
      option - The option to get the description from.
      Returns:
      the option description or an empty string if the description is null.
      Since:
      1.8.0

    • appendOption

      private void appendOption(StringBuilder buff, Option option, boolean required)
      Appends the usage clause for an Option to a StringBuffer.
      Parameters:
      buff - the StringBuffer to append to
      option - the Option to append
      required - whether the Option is required or not

    • appendOptionGroup

      private void appendOptionGroup(StringBuilder buff, OptionGroup group)
      Appends the usage clause for an OptionGroup to a StringBuffer. The clause is wrapped in square brackets if the group is required. The display of the options is handled by appendOption
      Parameters:
      buff - the StringBuilder to append to
      group - the group to append
      See Also:

    • appendOptions

      <A extends Appendable> A appendOptions(A sb, int width, Options options, int leftPad, int descPad) throws IOException
      Renders the specified Options and return the rendered Options in a StringBuffer.
      Parameters:
      sb - The StringBuffer to place the rendered Options into.
      width - The number of characters to display per line
      options - The command line Options
      leftPad - the number of characters of padding to be prefixed to each line
      descPad - the number of characters of padding to be prefixed to each description line
      Returns:
      the StringBuffer with the rendered Options contents.
      Throws:
      IOException - if an I/O error occurs.

    • appendWrappedText

      <A extends Appendable> A appendWrappedText(A appendable, int width, int nextLineTabStop, String text) throws IOException
      Renders the specified text and return the rendered Options in a StringBuffer.
      Type Parameters:
      A - The Appendable implementation.
      Parameters:
      appendable - The StringBuffer to place the rendered text into.
      width - The number of characters to display per line
      nextLineTabStop - The position on the next line for the first tab.
      text - The text to be rendered.
      Returns:
      the StringBuffer with the rendered Options contents.
      Throws:
      IOException - if an I/O error occurs.

    • createPadding

      protected String createPadding(int len)
      Creates a String of padding of length len.
      Parameters:
      len - The length of the String of padding to create.
      Returns:
      The String of padding

    • determineMaxSinceLength

      private int determineMaxSinceLength(Options options)

    • findWrapPos

      protected int findWrapPos(String text, int width, int startPos)
      Finds the next text wrap position after startPos for the text in text with the column width width. The wrap point is the last position before startPos+width having a whitespace character (space, \n, \r). If there is no whitespace character before startPos+width, it will return startPos+width.
      Parameters:
      text - The text being searched for the wrap position
      width - width of the wrapped text
      startPos - position from which to start the lookup whitespace character
      Returns:
      position on which the text must be wrapped or -1 if the wrap position is at the end of the text

    • getArgName

      public String getArgName()
      Gets the 'argName'.
      Returns:
      the 'argName'

    • getDescPadding

      public int getDescPadding()
      Gets the 'descPadding'.
      Returns:
      the 'descPadding'

    • getLeftPadding

      public int getLeftPadding()
      Gets the 'leftPadding'.
      Returns:
      the 'leftPadding'

    • getLongOptPrefix

      public String getLongOptPrefix()
      Gets the 'longOptPrefix'.
      Returns:
      the 'longOptPrefix'

    • getLongOptSeparator

      public String getLongOptSeparator()
      Gets the separator displayed between a long option and its value.
      Returns:
      the separator
      Since:
      1.3

    • getNewLine

      public String getNewLine()
      Gets the 'newLine'.
      Returns:
      the 'newLine'

    • getOptionComparator

      public Comparator<Option> getOptionComparator()
      Comparator used to sort the options when they output in help text. Defaults to case-insensitive alphabetical sorting by option key.
      Returns:
      the Comparator currently in use to sort the options
      Since:
      1.2

    • getOptPrefix

      public String getOptPrefix()
      Gets the 'optPrefix'.
      Returns:
      the 'optPrefix'

    • getSyntaxPrefix

      public String getSyntaxPrefix()
      Gets the 'syntaxPrefix'.
      Returns:
      the 'syntaxPrefix'

    • getWidth

      public int getWidth()
      Gets the 'width'.
      Returns:
      the 'width'

    • printHelp

      public void printHelp(int width, String cmdLineSyntax, String header, Options options, String footer)
      Prints the help for options with the specified command line syntax. This method prints help information to System.out by default.
      Parameters:
      width - the number of characters to be displayed on each line
      cmdLineSyntax - the syntax for this application
      header - the banner to display at the beginning of the help
      options - the Options instance
      footer - the banner to display at the end of the help

    • printHelp

      public void printHelp(int width, String cmdLineSyntax, String header, Options options, String footer, boolean autoUsage)
      Prints the help for options with the specified command line syntax. This method prints help information to System.out by default.
      Parameters:
      width - the number of characters to be displayed on each line
      cmdLineSyntax - the syntax for this application
      header - the banner to display at the beginning of the help
      options - the Options instance
      footer - the banner to display at the end of the help
      autoUsage - whether to print an automatically generated usage statement

    • printHelp

      public void printHelp(PrintWriter pw, int width, String cmdLineSyntax, String header, Options options, int leftPad, int descPad, String footer)
      Prints the help for options with the specified command line syntax.
      Parameters:
      pw - the writer to which the help will be written
      width - the number of characters to be displayed on each line
      cmdLineSyntax - the syntax for this application
      header - the banner to display at the beginning of the help
      options - the Options instance
      leftPad - the number of characters of padding to be prefixed to each line
      descPad - the number of characters of padding to be prefixed to each description line
      footer - the banner to display at the end of the help
      Throws:
      IllegalStateException - if there is no room to print a line

    • printHelp

      public void printHelp(PrintWriter pw, int width, String cmdLineSyntax, String header, Options options, int leftPad, int descPad, String footer, boolean autoUsage)
      Prints the help for options with the specified command line syntax.
      Parameters:
      pw - the writer to which the help will be written
      width - the number of characters to be displayed on each line
      cmdLineSyntax - the syntax for this application
      header - the banner to display at the beginning of the help
      options - the Options instance
      leftPad - the number of characters of padding to be prefixed to each line
      descPad - the number of characters of padding to be prefixed to each description line
      footer - the banner to display at the end of the help
      autoUsage - whether to print an automatically generated usage statement
      Throws:
      IllegalStateException - if there is no room to print a line

    • printHelp

      public void printHelp(String cmdLineSyntax, Options options)
      Prints the help for options with the specified command line syntax. This method prints help information to System.out by default.
      Parameters:
      cmdLineSyntax - the syntax for this application
      options - the Options instance

    • printHelp

      public void printHelp(String cmdLineSyntax, Options options, boolean autoUsage)
      Prints the help for options with the specified command line syntax. This method prints help information to System.out by default.
      Parameters:
      cmdLineSyntax - the syntax for this application
      options - the Options instance
      autoUsage - whether to print an automatically generated usage statement

    • printHelp

      public void printHelp(String cmdLineSyntax, String header, Options options, String footer)
      Prints the help for options with the specified command line syntax. This method prints help information to System.out by default.
      Parameters:
      cmdLineSyntax - the syntax for this application
      header - the banner to display at the beginning of the help
      options - the Options instance
      footer - the banner to display at the end of the help

    • printHelp

      public void printHelp(String cmdLineSyntax, String header, Options options, String footer, boolean autoUsage)
      Prints the help for options with the specified command line syntax. This method prints help information to System.out by default.
      Parameters:
      cmdLineSyntax - the syntax for this application
      header - the banner to display at the beginning of the help
      options - the Options instance
      footer - the banner to display at the end of the help
      autoUsage - whether to print an automatically generated usage statement

    • printOptions

      public void printOptions(PrintWriter pw, int width, Options options, int leftPad, int descPad)
      Prints the help for the specified Options to the specified writer, using the specified width, left padding and description padding.
      Parameters:
      pw - The printWriter to write the help to
      width - The number of characters to display per line
      options - The command line Options
      leftPad - the number of characters of padding to be prefixed to each line
      descPad - the number of characters of padding to be prefixed to each description line

    • printUsage

      public void printUsage(PrintWriter pw, int width, String cmdLineSyntax)
      Prints the cmdLineSyntax to the specified writer, using the specified width.
      Parameters:
      pw - The printWriter to write the help to
      width - The number of characters per line for the usage statement.
      cmdLineSyntax - The usage statement.

    • printUsage

      public void printUsage(PrintWriter pw, int width, String app, Options options)
      Prints the usage statement for the specified application.
      Parameters:
      pw - The PrintWriter to print the usage statement
      width - The number of characters to display per line
      app - The application name
      options - The command line Options

    • printWrapped

      public void printWrapped(PrintWriter pw, int width, int nextLineTabStop, String text)
      Prints the specified text to the specified PrintWriter.
      Parameters:
      pw - The printWriter to write the help to
      width - The number of characters to display per line
      nextLineTabStop - The position on the next line for the first tab.
      text - The text to be written to the PrintWriter

    • printWrapped

      public void printWrapped(PrintWriter pw, int width, String text)
      Prints the specified text to the specified PrintWriter.
      Parameters:
      pw - The printWriter to write the help to
      width - The number of characters to display per line
      text - The text to be written to the PrintWriter

    • renderOptions

      protected StringBuffer renderOptions(StringBuffer sb, int width, Options options, int leftPad, int descPad)
      Renders the specified Options and return the rendered Options in a StringBuffer.
      Parameters:
      sb - The StringBuffer to place the rendered Options into.
      width - The number of characters to display per line
      options - The command line Options
      leftPad - the number of characters of padding to be prefixed to each line
      descPad - the number of characters of padding to be prefixed to each description line
      Returns:
      the StringBuffer with the rendered Options contents.

    • renderWrappedText

      protected StringBuffer renderWrappedText(StringBuffer sb, int width, int nextLineTabStop, String text)
      Renders the specified text and return the rendered Options in a StringBuffer.
      Parameters:
      sb - The StringBuffer to place the rendered text into.
      width - The number of characters to display per line
      nextLineTabStop - The position on the next line for the first tab.
      text - The text to be rendered.
      Returns:
      the StringBuffer with the rendered Options contents.

    • renderWrappedTextBlock

      private <A extends Appendable> A renderWrappedTextBlock(A appendable, int width, int nextLineTabStop, String text)
      Renders the specified text width a maximum width. This method differs from renderWrappedText by not removing leading spaces after a new line.
      Parameters:
      appendable - The StringBuffer to place the rendered text into.
      width - The number of characters to display per line
      nextLineTabStop - The position on the next line for the first tab.
      text - The text to be rendered.

    • rtrim

      protected String rtrim(String s)
      Removes the trailing whitespace from the specified String.
      Parameters:
      s - The String to remove the trailing padding from.
      Returns:
      The String of without the trailing padding

    • setArgName

      public void setArgName(String name)
      Sets the 'argName'.
      Parameters:
      name - the new value of 'argName'

    • setDescPadding

      public void setDescPadding(int padding)
      Sets the 'descPadding'.
      Parameters:
      padding - the new value of 'descPadding'

    • setLeftPadding

      public void setLeftPadding(int padding)
      Sets the 'leftPadding'.
      Parameters:
      padding - the new value of 'leftPadding'

    • setLongOptPrefix

      public void setLongOptPrefix(String prefix)
      Sets the 'longOptPrefix'.
      Parameters:
      prefix - the new value of 'longOptPrefix'

    • setLongOptSeparator

      public void setLongOptSeparator(String longOptSeparator)
      Sets the separator displayed between a long option and its value. Ensure that the separator specified is supported by the parser used, typically ' ' or '='.
      Parameters:
      longOptSeparator - the separator, typically ' ' or '='.
      Since:
      1.3

    • setNewLine

      public void setNewLine(String newline)
      Sets the 'newLine'.
      Parameters:
      newline - the new value of 'newLine'

    • setOptionComparator

      public void setOptionComparator(Comparator<Option> comparator)
      Sets the comparator used to sort the options when they output in help text. Passing in a null comparator will keep the options in the order they were declared.
      Parameters:
      comparator - the Comparator to use for sorting the options
      Since:
      1.2

    • setOptPrefix

      public void setOptPrefix(String prefix)
      Sets the 'optPrefix'.
      Parameters:
      prefix - the new value of 'optPrefix'

    • setSyntaxPrefix

      public void setSyntaxPrefix(String prefix)
      Sets the 'syntaxPrefix'.
      Parameters:
      prefix - the new value of 'syntaxPrefix'

    • setWidth

      public void setWidth(int width)
      Sets the 'width'.
      Parameters:
      width - the new value of 'width'