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

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