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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `HelpFormatter.Builder`
  Builds `HelpFormatter`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_ARG_NAME`
  Default name for an argument
  `static final int`
  `DEFAULT_DESC_PAD`
  Number of space characters to be prefixed to each description line
  `static final int`
  `DEFAULT_LEFT_PAD`
  Default padding to the left of each line
  `static final String`
  `DEFAULT_LONG_OPT_PREFIX`
  Default prefix for long Option
  `static final String`
  `DEFAULT_LONG_OPT_SEPARATOR`
  Default separator displayed between a long Option and its value
  `static final String`
  `DEFAULT_OPT_PREFIX`
  Default prefix for shortOpts
  `static final String`
  `DEFAULT_SYNTAX_PREFIX`
  The string to display at the beginning of the usage statement
  `static final int`
  `DEFAULT_WIDTH`
  Default number of characters per line
  `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.
  `String`
  `defaultLongOptPrefix`
  Deprecated.
  Scope will be made private for next major version - use get/setLongOptPrefix methods instead.
  `String`
  `defaultNewLine`
  Deprecated.
  Scope will be made private for next major version - use get/setNewLine methods instead.
  `String`
  `defaultOptPrefix`
  Deprecated.
  Scope will be made private for next major version - use get/setOptPrefix methods instead.
  `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 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
  Description
  `HelpFormatter()`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static HelpFormatter.Builder`
  `builder()`
  Creates a new builder.
  `protected String`
  `createPadding(int len)`
  Creates a String of padding of length `len`.
  `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`.
  `String`
  `getArgName()`
  Gets the 'argName'.
  `int`
  `getDescPadding()`
  Gets the 'descPadding'.
  `static String`
  `getDescription(Option option)`
  Gets the option description or an empty string if the description is `null`.
  `int`
  `getLeftPadding()`
  Gets the 'leftPadding'.
  `String`
  `getLongOptPrefix()`
  Gets the 'longOptPrefix'.
  `String`
  `getLongOptSeparator()`
  Gets the separator displayed between a long option and its value.
  `String`
  `getNewLine()`
  Gets the 'newLine'.
  `Comparator<Option>`
  `getOptionComparator()`
  Comparator used to sort the options when they output in help text.
  `String`
  `getOptPrefix()`
  Gets the 'optPrefix'.
  `String`
  `getSyntaxPrefix()`
  Gets the 'syntaxPrefix'.
  `int`
  `getWidth()`
  Gets the 'width'.
  `void`
  `printHelp(int width, String cmdLineSyntax, String header, Options options, String footer)`
  Prints the help for `options` with the specified command line syntax.
  `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.
  `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.
  `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.
  `void`
  `printHelp(String cmdLineSyntax, String header, Options options, String footer)`
  Prints the help for `options` with the specified command line syntax.
  `void`
  `printHelp(String cmdLineSyntax, String header, Options options, String footer, boolean autoUsage)`
  Prints the help for `options` with the specified command line syntax.
  `void`
  `printHelp(String cmdLineSyntax, Options options)`
  Prints the help for `options` with the specified command line syntax.
  `void`
  `printHelp(String cmdLineSyntax, Options options, boolean autoUsage)`
  Prints the help for `options` with the specified command line syntax.
  `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.
  `void`
  `printUsage(PrintWriter pw, int width, String cmdLineSyntax)`
  Prints the cmdLineSyntax to the specified writer, using the specified width.
  `void`
  `printUsage(PrintWriter pw, int width, String app, Options options)`
  Prints the usage statement for the specified application.
  `void`
  `printWrapped(PrintWriter pw, int width, int nextLineTabStop, String text)`
  Prints the specified text to the specified PrintWriter.
  `void`
  `printWrapped(PrintWriter pw, int width, String text)`
  Prints the specified text to the specified PrintWriter.
  `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.
  `protected StringBuffer`
  `renderWrappedText(StringBuffer sb, int width, int nextLineTabStop, String text)`
  Renders the specified text and return the rendered Options in a StringBuffer.
  `protected String`
  `rtrim(String s)`
  Removes the trailing whitespace from the specified String.
  `void`
  `setArgName(String name)`
  Sets the 'argName'.
  `void`
  `setDescPadding(int padding)`
  Sets the 'descPadding'.
  `void`
  `setLeftPadding(int padding)`
  Sets the 'leftPadding'.
  `void`
  `setLongOptPrefix(String prefix)`
  Sets the 'longOptPrefix'.
  `void`
  `setLongOptSeparator(String longOptSeparator)`
  Sets the separator displayed between a long option and its value.
  `void`
  `setNewLine(String newline)`
  Sets the 'newLine'.
  `void`
  `setOptionComparator(Comparator<Option> comparator)`
  Sets the comparator used to sort the options when they output in help text.
  `void`
  `setOptPrefix(String prefix)`
  Sets the 'optPrefix'.
  `void`
  `setSyntaxPrefix(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 Details

  - ### 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 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 String DEFAULT_OPT_PREFIX
    Default prefix for shortOpts
    See Also:
      - Constant Field Values

  - ### DEFAULT_LONG_OPT_PREFIX

    public static final String DEFAULT_LONG_OPT_PREFIX
    Default prefix for long Option
    See Also:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### DEFAULT_ARG_NAME

    public static final 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 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

- ## Constructor Details

  - ### HelpFormatter

    public HelpFormatter()
    Constructs a new instance.

- ## Method Details

  - ### builder

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

  - ### 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

  - ### 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

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

  - ### 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'