HelpFormatter
Date: 2017-04-22

org.apache.commons.cli

## Class HelpFormatter

- java.lang.Object
- - org.apache.commons.cli.HelpFormatter

-     public class HelpFormatter
      extends java.lang.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 http://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 http://example.com/issues

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DEFAULT_ARG_NAME` default name for an argument
    `static int` | `DEFAULT_DESC_PAD` number of space characters to be prefixed to each description line
    `static int` | `DEFAULT_LEFT_PAD` default padding to the left of each line
    `static java.lang.String` | `DEFAULT_LONG_OPT_PREFIX` default prefix for long Option
    `static java.lang.String` | `DEFAULT_LONG_OPT_SEPARATOR` default separator displayed between a long Option and its value
    `static java.lang.String` | `DEFAULT_OPT_PREFIX` default prefix for shortOpts
    `static java.lang.String` | `DEFAULT_SYNTAX_PREFIX` the string to display at the beginning of the usage statement
    `static int` | `DEFAULT_WIDTH` default number of characters per line
    `java.lang.String` | `defaultArgName` Deprecated. Scope will be made private for next major version - use get/setArgName methods instead.
    `int` | `defaultDescPad` Deprecated. Scope will be made private for next major version - use get/setDescPadding methods instead.
    `int` | `defaultLeftPad` Deprecated. Scope will be made private for next major version - use get/setLeftPadding methods instead.
    `java.lang.String` | `defaultLongOptPrefix` Deprecated. Scope will be made private for next major version - use get/setLongOptPrefix methods instead.
    `java.lang.String` | `defaultNewLine` Deprecated. Scope will be made private for next major version - use get/setNewLine methods instead.
    `java.lang.String` | `defaultOptPrefix` Deprecated. Scope will be made private for next major version - use get/setOptPrefix methods instead.
    `java.lang.String` | `defaultSyntaxPrefix` Deprecated. Scope will be made private for next major version - use get/setSyntaxPrefix methods instead.
    `int` | `defaultWidth` Deprecated. Scope will be made private for next major version - use get/setWidth methods instead.
    `protected java.util.Comparator<Option>` | `optionComparator` Comparator used to sort the options when they output in help text Defaults to case-insensitive alphabetical sorting by option key

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `HelpFormatter()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected java.lang.String` | `createPadding(int len)` Return a String of padding of length `len`.
    `protected int` | `findWrapPos(java.lang.String text, int width, int startPos)` Finds the next text wrap position after `startPos` for the text in `text` with the column width `width`.
    `java.lang.String` | `getArgName()` Returns the 'argName'.
    `int` | `getDescPadding()` Returns the 'descPadding'.
    `int` | `getLeftPadding()` Returns the 'leftPadding'.
    `java.lang.String` | `getLongOptPrefix()` Returns the 'longOptPrefix'.
    `java.lang.String` | `getLongOptSeparator()` Returns the separator displayed between a long option and its value.
    `java.lang.String` | `getNewLine()` Returns the 'newLine'.
    `java.util.Comparator<Option>` | `getOptionComparator()` Comparator used to sort the options when they output in help text.
    `java.lang.String` | `getOptPrefix()` Returns the 'optPrefix'.
    `java.lang.String` | `getSyntaxPrefix()` Returns the 'syntaxPrefix'.
    `int` | `getWidth()` Returns the 'width'.
    `void` | `printHelp(int width, java.lang.String cmdLineSyntax, java.lang.String header, Options options, java.lang.String footer)` Print the help for `options` with the specified command line syntax.
    `void` | `printHelp(int width, java.lang.String cmdLineSyntax, java.lang.String header, Options options, java.lang.String footer, boolean autoUsage)` Print the help for `options` with the specified command line syntax.
    `void` | `printHelp(java.io.PrintWriter pw, int width, java.lang.String cmdLineSyntax, java.lang.String header, Options options, int leftPad, int descPad, java.lang.String footer)` Print the help for `options` with the specified command line syntax.
    `void` | `printHelp(java.io.PrintWriter pw, int width, java.lang.String cmdLineSyntax, java.lang.String header, Options options, int leftPad, int descPad, java.lang.String footer, boolean autoUsage)` Print the help for `options` with the specified command line syntax.
    `void` | `printHelp(java.lang.String cmdLineSyntax, Options options)` Print the help for `options` with the specified command line syntax.
    `void` | `printHelp(java.lang.String cmdLineSyntax, Options options, boolean autoUsage)` Print the help for `options` with the specified command line syntax.
    `void` | `printHelp(java.lang.String cmdLineSyntax, java.lang.String header, Options options, java.lang.String footer)` Print the help for `options` with the specified command line syntax.
    `void` | `printHelp(java.lang.String cmdLineSyntax, java.lang.String header, Options options, java.lang.String footer, boolean autoUsage)` Print the help for `options` with the specified command line syntax.
    `void` | `printOptions(java.io.PrintWriter pw, int width, Options options, int leftPad, int descPad)` Print the help for the specified Options to the specified writer, using the specified width, left padding and description padding.
    `void` | `printUsage(java.io.PrintWriter pw, int width, java.lang.String cmdLineSyntax)` Print the cmdLineSyntax to the specified writer, using the specified width.
    `void` | `printUsage(java.io.PrintWriter pw, int width, java.lang.String app, Options options)` Prints the usage statement for the specified application.
    `void` | `printWrapped(java.io.PrintWriter pw, int width, int nextLineTabStop, java.lang.String text)` Print the specified text to the specified PrintWriter.
    `void` | `printWrapped(java.io.PrintWriter pw, int width, java.lang.String text)` Print the specified text to the specified PrintWriter.
    `protected java.lang.StringBuffer` | `renderOptions(java.lang.StringBuffer sb, int width, Options options, int leftPad, int descPad)` Render the specified Options and return the rendered Options in a StringBuffer.
    `protected java.lang.StringBuffer` | `renderWrappedText(java.lang.StringBuffer sb, int width, int nextLineTabStop, java.lang.String text)` Render the specified text and return the rendered Options in a StringBuffer.
    `protected java.lang.String` | `rtrim(java.lang.String s)` Remove the trailing whitespace from the specified String.
    `void` | `setArgName(java.lang.String name)` Sets the 'argName'.
    `void` | `setDescPadding(int padding)` Sets the 'descPadding'.
    `void` | `setLeftPadding(int padding)` Sets the 'leftPadding'.
    `void` | `setLongOptPrefix(java.lang.String prefix)` Sets the 'longOptPrefix'.
    `void` | `setLongOptSeparator(java.lang.String longOptSeparator)` Set the separator displayed between a long option and its value.
    `void` | `setNewLine(java.lang.String newline)` Sets the 'newLine'.
    `void` | `setOptionComparator(java.util.Comparator<Option> comparator)` Set the comparator used to sort the options when they output in help text.
    `void` | `setOptPrefix(java.lang.String prefix)` Sets the 'optPrefix'.
    `void` | `setSyntaxPrefix(java.lang.String prefix)` Sets the 'syntaxPrefix'.
    `void` | `setWidth(int width)` Sets the 'width'.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_WIDTH

          public static final int DEFAULT_WIDTH

      default number of characters per line
      See Also:
        Constant Field Values

    - #### DEFAULT_LEFT_PAD

          public static final int DEFAULT_LEFT_PAD

      default padding to the left of each line
      See Also:
        Constant Field Values

    - #### DEFAULT_DESC_PAD

          public static final int DEFAULT_DESC_PAD

      number of space characters to be prefixed to each description line
      See Also:
        Constant Field Values

    - #### DEFAULT_SYNTAX_PREFIX

          public static final java.lang.String DEFAULT_SYNTAX_PREFIX

      the string to display at the beginning of the usage statement
      See Also:
        Constant Field Values

    - #### DEFAULT_OPT_PREFIX

          public static final java.lang.String DEFAULT_OPT_PREFIX

      default prefix for shortOpts
      See Also:
        Constant Field Values

    - #### DEFAULT_LONG_OPT_PREFIX

          public static final java.lang.String DEFAULT_LONG_OPT_PREFIX

      default prefix for long Option
      See Also:
        Constant Field Values

    - #### DEFAULT_LONG_OPT_SEPARATOR

          public static final java.lang.String DEFAULT_LONG_OPT_SEPARATOR

      default separator displayed between a long Option and its value
      Since:
        1.3
      See Also:
        Constant Field Values

    - #### DEFAULT_ARG_NAME

          public static final java.lang.String DEFAULT_ARG_NAME

      default name for an argument
      See Also:
        Constant Field Values

    - #### 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 java.lang.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 java.lang.String defaultNewLine

      Deprecated. Scope will be made private for next major version - use get/setNewLine methods instead.
      the new line string

    - #### defaultOptPrefix

          @Deprecated
          public java.lang.String defaultOptPrefix

      Deprecated. Scope will be made private for next major version - use get/setOptPrefix methods instead.
      the shortOpt prefix

    - #### defaultLongOptPrefix

          @Deprecated
          public java.lang.String defaultLongOptPrefix

      Deprecated. Scope will be made private for next major version - use get/setLongOptPrefix methods instead.
      the long Opt prefix

    - #### defaultArgName

          @Deprecated
          public java.lang.String defaultArgName

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

    - #### optionComparator

          protected java.util.Comparator<Option> optionComparator

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

  - ### Constructor Detail

    - #### HelpFormatter

          public HelpFormatter()

  - ### Method Detail

    - #### setWidth

          public void setWidth(int width)

      Sets the 'width'.
      Parameters:
        `width` - the new value of 'width'

    - #### getWidth

          public int getWidth()

      Returns the 'width'.
      Returns:
        the 'width'

    - #### setLeftPadding

          public void setLeftPadding(int padding)

      Sets the 'leftPadding'.
      Parameters:
        `padding` - the new value of 'leftPadding'

    - #### getLeftPadding

          public int getLeftPadding()

      Returns the 'leftPadding'.
      Returns:
        the 'leftPadding'

    - #### setDescPadding

          public void setDescPadding(int padding)

      Sets the 'descPadding'.
      Parameters:
        `padding` - the new value of 'descPadding'

    - #### getDescPadding

          public int getDescPadding()

      Returns the 'descPadding'.
      Returns:
        the 'descPadding'

    - #### setSyntaxPrefix

          public void setSyntaxPrefix(java.lang.String prefix)

      Sets the 'syntaxPrefix'.
      Parameters:
        `prefix` - the new value of 'syntaxPrefix'

    - #### getSyntaxPrefix

          public java.lang.String getSyntaxPrefix()

      Returns the 'syntaxPrefix'.
      Returns:
        the 'syntaxPrefix'

    - #### setNewLine

          public void setNewLine(java.lang.String newline)

      Sets the 'newLine'.
      Parameters:
        `newline` - the new value of 'newLine'

    - #### getNewLine

          public java.lang.String getNewLine()

      Returns the 'newLine'.
      Returns:
        the 'newLine'

    - #### setOptPrefix

          public void setOptPrefix(java.lang.String prefix)

      Sets the 'optPrefix'.
      Parameters:
        `prefix` - the new value of 'optPrefix'

    - #### getOptPrefix

          public java.lang.String getOptPrefix()

      Returns the 'optPrefix'.
      Returns:
        the 'optPrefix'

    - #### setLongOptPrefix

          public void setLongOptPrefix(java.lang.String prefix)

      Sets the 'longOptPrefix'.
      Parameters:
        `prefix` - the new value of 'longOptPrefix'

    - #### getLongOptPrefix

          public java.lang.String getLongOptPrefix()

      Returns the 'longOptPrefix'.
      Returns:
        the 'longOptPrefix'

    - #### setLongOptSeparator

          public void setLongOptSeparator(java.lang.String longOptSeparator)

      Set 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

    - #### getLongOptSeparator

          public java.lang.String getLongOptSeparator()

      Returns the separator displayed between a long option and its value.
      Returns:
        the separator
      Since:
        1.3

    - #### setArgName

          public void setArgName(java.lang.String name)

      Sets the 'argName'.
      Parameters:
        `name` - the new value of 'argName'

    - #### getArgName

          public java.lang.String getArgName()

      Returns the 'argName'.
      Returns:
        the 'argName'

    - #### getOptionComparator

          public java.util.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

    - #### setOptionComparator

          public void setOptionComparator(java.util.Comparator<Option> comparator)

      Set 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

    - #### printHelp

          public void printHelp(java.lang.String cmdLineSyntax,
                       Options options)

      Print the help for `options` with the specified command line syntax. This method prints help information to System.out.
      Parameters:
        `cmdLineSyntax` - the syntax for this application
        `options` - the Options instance

    - #### printHelp

          public void printHelp(java.lang.String cmdLineSyntax,
                       Options options,
                       boolean autoUsage)

      Print the help for `options` with the specified command line syntax. This method prints help information to System.out.
      Parameters:
        `cmdLineSyntax` - the syntax for this application
        `options` - the Options instance
        `autoUsage` - whether to print an automatically generated usage statement

    - #### printHelp

          public void printHelp(java.lang.String cmdLineSyntax,
                       java.lang.String header,
                       Options options,
                       java.lang.String footer)

      Print the help for `options` with the specified command line syntax. This method prints help information to System.out.
      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(java.lang.String cmdLineSyntax,
                       java.lang.String header,
                       Options options,
                       java.lang.String footer,
                       boolean autoUsage)

      Print the help for `options` with the specified command line syntax. This method prints help information to System.out.
      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

    - #### printHelp

          public void printHelp(int width,
                       java.lang.String cmdLineSyntax,
                       java.lang.String header,
                       Options options,
                       java.lang.String footer)

      Print the help for `options` with the specified command line syntax. This method prints help information to System.out.
      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,
                       java.lang.String cmdLineSyntax,
                       java.lang.String header,
                       Options options,
                       java.lang.String footer,
                       boolean autoUsage)

      Print the help for `options` with the specified command line syntax. This method prints help information to System.out.
      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(java.io.PrintWriter pw,
                       int width,
                       java.lang.String cmdLineSyntax,
                       java.lang.String header,
                       Options options,
                       int leftPad,
                       int descPad,
                       java.lang.String footer)

      Print 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:
        `java.lang.IllegalStateException` - if there is no room to print a line

    - #### printHelp

          public void printHelp(java.io.PrintWriter pw,
                       int width,
                       java.lang.String cmdLineSyntax,
                       java.lang.String header,
                       Options options,
                       int leftPad,
                       int descPad,
                       java.lang.String footer,
                       boolean autoUsage)

      Print 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:
        `java.lang.IllegalStateException` - if there is no room to print a line

    - #### printUsage

          public void printUsage(java.io.PrintWriter pw,
                        int width,
                        java.lang.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

    - #### printUsage

          public void printUsage(java.io.PrintWriter pw,
                        int width,
                        java.lang.String cmdLineSyntax)

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

    - #### printOptions

          public void printOptions(java.io.PrintWriter pw,
                          int width,
                          Options options,
                          int leftPad,
                          int descPad)

      Print 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

    - #### printWrapped

          public void printWrapped(java.io.PrintWriter pw,
                          int width,
                          java.lang.String text)

      Print 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

    - #### printWrapped

          public void printWrapped(java.io.PrintWriter pw,
                          int width,
                          int nextLineTabStop,
                          java.lang.String text)

      Print 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

    - #### renderOptions

          protected java.lang.StringBuffer renderOptions(java.lang.StringBuffer sb,
                                             int width,
                                             Options options,
                                             int leftPad,
                                             int descPad)

      Render 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 java.lang.StringBuffer renderWrappedText(java.lang.StringBuffer sb,
                                                 int width,
                                                 int nextLineTabStop,
                                                 java.lang.String text)

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

    - #### findWrapPos

          protected int findWrapPos(java.lang.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

    - #### createPadding

          protected java.lang.String createPadding(int len)

      Return a String of padding of length `len`.
      Parameters:
        `len` - The length of the String of padding to create.
      Returns:
        The String of padding

    - #### rtrim

          protected java.lang.String rtrim(java.lang.String s)

      Remove 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