Package org.apache.commons.cli
Class HelpFormatter
java.lang.Object
org.apache.commons.cli.HelpFormatter
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
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
Default name for an argumentstatic final int
Number of space characters to be prefixed to each description linestatic final int
Default padding to the left of each linestatic final String
Default prefix for long Optionstatic final String
Default separator displayed between a long Option and its valuestatic final String
Default prefix for shortOptsstatic final String
The string to display at the beginning of the usage statementstatic final int
Default number of characters per lineDeprecated.Scope will be made private for next major version - use get/setArgName methods instead.int
Deprecated.Scope will be made private for next major version - use get/setDescPadding methods instead.int
Deprecated.Scope will be made private for next major version - use get/setLeftPadding methods instead.Deprecated.Scope will be made private for next major version - use get/setLongOptPrefix methods instead.Deprecated.Scope will be made private for next major version - use get/setNewLine methods instead.Deprecated.Scope will be made private for next major version - use get/setOptPrefix methods instead.Deprecated.Scope will be made private for next major version - use get/setSyntaxPrefix methods instead.int
Deprecated.Scope will be made private for next major version - use get/setWidth methods instead.protected Comparator<Option>
Comparator used to sort the options when they output in help text Defaults to case-insensitive alphabetical sorting by option key -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic HelpFormatter.Builder
builder()
Creates a new builder.protected String
createPadding
(int len) Creates a String of padding of lengthlen
.protected int
findWrapPos
(String text, int width, int startPos) Finds the next text wrap position afterstartPos
for the text intext
with the column widthwidth
.Gets the 'argName'.int
Gets the 'descPadding'.static String
getDescription
(Option option) Gets the option description or an empty string if the description isnull
.int
Gets the 'leftPadding'.Gets the 'longOptPrefix'.Gets the separator displayed between a long option and its value.Gets the 'newLine'.Comparator used to sort the options when they output in help text.Gets the 'optPrefix'.Gets the 'syntaxPrefix'.int
getWidth()
Gets the 'width'.void
Prints the help foroptions
with the specified command line syntax.void
printHelp
(int width, String cmdLineSyntax, String header, Options options, String footer, boolean autoUsage) Prints the help foroptions
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 foroptions
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 foroptions
with the specified command line syntax.void
Prints the help foroptions
with the specified command line syntax.void
Prints the help foroptions
with the specified command line syntax.void
Prints the help foroptions
with the specified command line syntax.void
Prints the help foroptions
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
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'.
-
Field Details
-
DEFAULT_WIDTH
Default number of characters per line- See Also:
-
DEFAULT_LEFT_PAD
Default padding to the left of each line- See Also:
-
DEFAULT_DESC_PAD
Number of space characters to be prefixed to each description line- See Also:
-
DEFAULT_SYNTAX_PREFIX
The string to display at the beginning of the usage statement- See Also:
-
DEFAULT_OPT_PREFIX
Default prefix for shortOpts- See Also:
-
DEFAULT_LONG_OPT_PREFIX
Default prefix for long Option- See Also:
-
DEFAULT_LONG_OPT_SEPARATOR
Default separator displayed between a long Option and its value- Since:
- 1.3
- See Also:
-
DEFAULT_ARG_NAME
Default name for an argument- See Also:
-
defaultWidth
Deprecated.Scope will be made private for next major version - use get/setWidth methods instead.Number of characters per line -
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.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.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.Scope will be made private for next major version - use get/setNewLine methods instead.The new line string -
defaultOptPrefix
Deprecated.Scope will be made private for next major version - use get/setOptPrefix methods instead.The shortOpt prefix -
defaultLongOptPrefix
Deprecated.Scope will be made private for next major version - use get/setLongOptPrefix methods instead.The long Opt prefix -
defaultArgName
Deprecated.Scope will be made private for next major version - use get/setArgName methods instead.The name of the argument -
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
Creates a new builder.- Returns:
- a new builder.
- Since:
- 1.7.0
-
getDescription
Gets the option description or an empty string if the description isnull
.- 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
Creates a String of padding of lengthlen
.- Parameters:
len
- The length of the String of padding to create.- Returns:
- The String of padding
-
findWrapPos
Finds the next text wrap position afterstartPos
for the text intext
with the column widthwidth
. 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 positionwidth
- width of the wrapped textstartPos
- 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
Gets the 'argName'.- Returns:
- the 'argName'
-
getDescPadding
Gets the 'descPadding'.- Returns:
- the 'descPadding'
-
getLeftPadding
Gets the 'leftPadding'.- Returns:
- the 'leftPadding'
-
getLongOptPrefix
Gets the 'longOptPrefix'.- Returns:
- the 'longOptPrefix'
-
getLongOptSeparator
Gets the separator displayed between a long option and its value.- Returns:
- the separator
- Since:
- 1.3
-
getNewLine
Gets the 'newLine'.- Returns:
- the 'newLine'
-
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
Gets the 'optPrefix'.- Returns:
- the 'optPrefix'
-
getSyntaxPrefix
Gets the 'syntaxPrefix'.- Returns:
- the 'syntaxPrefix'
-
getWidth
Gets the 'width'.- Returns:
- the 'width'
-
printHelp
public void printHelp(int width, String cmdLineSyntax, String header, Options options, String footer) Prints the help foroptions
with the specified command line syntax. This method prints help information toSystem.out
by default.- Parameters:
width
- the number of characters to be displayed on each linecmdLineSyntax
- the syntax for this applicationheader
- the banner to display at the beginning of the helpoptions
- the Options instancefooter
- 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 foroptions
with the specified command line syntax. This method prints help information toSystem.out
by default.- Parameters:
width
- the number of characters to be displayed on each linecmdLineSyntax
- the syntax for this applicationheader
- the banner to display at the beginning of the helpoptions
- the Options instancefooter
- the banner to display at the end of the helpautoUsage
- 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 foroptions
with the specified command line syntax.- Parameters:
pw
- the writer to which the help will be writtenwidth
- the number of characters to be displayed on each linecmdLineSyntax
- the syntax for this applicationheader
- the banner to display at the beginning of the helpoptions
- the Options instanceleftPad
- the number of characters of padding to be prefixed to each linedescPad
- the number of characters of padding to be prefixed to each description linefooter
- 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 foroptions
with the specified command line syntax.- Parameters:
pw
- the writer to which the help will be writtenwidth
- the number of characters to be displayed on each linecmdLineSyntax
- the syntax for this applicationheader
- the banner to display at the beginning of the helpoptions
- the Options instanceleftPad
- the number of characters of padding to be prefixed to each linedescPad
- the number of characters of padding to be prefixed to each description linefooter
- the banner to display at the end of the helpautoUsage
- whether to print an automatically generated usage statement- Throws:
IllegalStateException
- if there is no room to print a line
-
printHelp
Prints the help foroptions
with the specified command line syntax. This method prints help information toSystem.out
by default.- Parameters:
cmdLineSyntax
- the syntax for this applicationoptions
- the Options instance
-
printHelp
Prints the help foroptions
with the specified command line syntax. This method prints help information toSystem.out
by default.- Parameters:
cmdLineSyntax
- the syntax for this applicationoptions
- the Options instanceautoUsage
- whether to print an automatically generated usage statement
-
printHelp
Prints the help foroptions
with the specified command line syntax. This method prints help information toSystem.out
by default.- Parameters:
cmdLineSyntax
- the syntax for this applicationheader
- the banner to display at the beginning of the helpoptions
- the Options instancefooter
- 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 foroptions
with the specified command line syntax. This method prints help information toSystem.out
by default.- Parameters:
cmdLineSyntax
- the syntax for this applicationheader
- the banner to display at the beginning of the helpoptions
- the Options instancefooter
- the banner to display at the end of the helpautoUsage
- whether to print an automatically generated usage statement
-
printOptions
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 towidth
- The number of characters to display per lineoptions
- The command line OptionsleftPad
- the number of characters of padding to be prefixed to each linedescPad
- the number of characters of padding to be prefixed to each description line
-
printUsage
Prints the cmdLineSyntax to the specified writer, using the specified width.- Parameters:
pw
- The printWriter to write the help towidth
- The number of characters per line for the usage statement.cmdLineSyntax
- The usage statement.
-
printUsage
Prints the usage statement for the specified application.- Parameters:
pw
- The PrintWriter to print the usage statementwidth
- The number of characters to display per lineapp
- The application nameoptions
- The command line Options
-
printWrapped
Prints the specified text to the specified PrintWriter.- Parameters:
pw
- The printWriter to write the help towidth
- The number of characters to display per linenextLineTabStop
- The position on the next line for the first tab.text
- The text to be written to the PrintWriter
-
printWrapped
Prints the specified text to the specified PrintWriter.- Parameters:
pw
- The printWriter to write the help towidth
- The number of characters to display per linetext
- 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 lineoptions
- The command line OptionsleftPad
- the number of characters of padding to be prefixed to each linedescPad
- 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 linenextLineTabStop
- 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
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
Sets the 'argName'.- Parameters:
name
- the new value of 'argName'
-
setDescPadding
Sets the 'descPadding'.- Parameters:
padding
- the new value of 'descPadding'
-
setLeftPadding
Sets the 'leftPadding'.- Parameters:
padding
- the new value of 'leftPadding'
-
setLongOptPrefix
Sets the 'longOptPrefix'.- Parameters:
prefix
- the new value of 'longOptPrefix'
-
setLongOptSeparator
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
Sets the 'newLine'.- Parameters:
newline
- the new value of 'newLine'
-
setOptionComparator
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
- theComparator
to use for sorting the options- Since:
- 1.2
-
setOptPrefix
Sets the 'optPrefix'.- Parameters:
prefix
- the new value of 'optPrefix'
-
setSyntaxPrefix
Sets the 'syntaxPrefix'.- Parameters:
prefix
- the new value of 'syntaxPrefix'
-
setWidth
Sets the 'width'.- Parameters:
width
- the new value of 'width'
-