Package 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
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
HelpFormatter.OptionComparator
This class implements theComparator
interface for comparing Options.
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
DEFAULT_ARG_NAME
Default name for an argumentstatic int
DEFAULT_DESC_PAD
number of space characters to be prefixed to each description linestatic int
DEFAULT_LEFT_PAD
Default padding to the left of each linestatic java.lang.String
DEFAULT_LONG_OPT_PREFIX
Default prefix for long Optionstatic java.lang.String
DEFAULT_LONG_OPT_SEPARATOR
default separator displayed between a long Option and its valuestatic java.lang.String
DEFAULT_OPT_PREFIX
Default prefix for shortOptsstatic java.lang.String
DEFAULT_SYNTAX_PREFIX
The string to display at the beginning of the usage statementstatic int
DEFAULT_WIDTH
Default number of characters per linejava.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.private java.lang.String
longOptSeparator
The separator displayed between the long option and its value.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 Description HelpFormatter()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description private void
appendOption(java.lang.StringBuffer buff, Option option, boolean required)
Appends the usage clause for an Option to a StringBuffer.private void
appendOptionGroup(java.lang.StringBuffer buff, OptionGroup group)
Appends the usage clause for an OptionGroup to a StringBuffer.protected java.lang.String
createPadding(int len)
Return a String of padding of lengthlen
.protected int
findWrapPos(java.lang.String text, int width, int startPos)
Finds the next text wrap position afterstartPos
for the text intext
with the column widthwidth
.java.lang.String
getArgName()
Gets the 'argName'.int
getDescPadding()
Gets the 'descPadding'.int
getLeftPadding()
Gets the 'leftPadding'.java.lang.String
getLongOptPrefix()
Gets the 'longOptPrefix'.java.lang.String
getLongOptSeparator()
Gets the separator displayed between a long option and its value.java.lang.String
getNewLine()
Gets the 'newLine'.java.util.Comparator<Option>
getOptionComparator()
Comparator used to sort the options when they output in help text.java.lang.String
getOptPrefix()
Gets the 'optPrefix'.java.lang.String
getSyntaxPrefix()
Gets the 'syntaxPrefix'.int
getWidth()
Gets the 'width'.void
printHelp(int width, java.lang.String cmdLineSyntax, java.lang.String header, Options options, java.lang.String footer)
Print the help foroptions
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 foroptions
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 foroptions
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 foroptions
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 foroptions
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 foroptions
with the specified command line syntax.void
printHelp(java.lang.String cmdLineSyntax, Options options)
Print the help foroptions
with the specified command line syntax.void
printHelp(java.lang.String cmdLineSyntax, Options options, boolean autoUsage)
Print the help foroptions
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.private java.lang.Appendable
renderWrappedTextBlock(java.lang.StringBuffer sb, int width, int nextLineTabStop, java.lang.String text)
Render the specified text width a maximum width.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'.
-
-
-
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
-
longOptSeparator
private java.lang.String longOptSeparator
The separator displayed between the long option and its value.
-
-
Method Detail
-
appendOption
private void appendOption(java.lang.StringBuffer buff, Option option, boolean required)
Appends the usage clause for an Option to a StringBuffer.- Parameters:
buff
- the StringBuffer to append tooption
- the Option to appendrequired
- whether the Option is required or not
-
appendOptionGroup
private void appendOptionGroup(java.lang.StringBuffer 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 StringBuffer to append togroup
- the group to append- See Also:
appendOption(StringBuffer,Option,boolean)
-
createPadding
protected java.lang.String createPadding(int len)
Return a String of padding of lengthlen
.- Parameters:
len
- The length of the String of padding to create.- Returns:
- The String of padding
-
findWrapPos
protected int findWrapPos(java.lang.String text, int width, int startPos)
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
public java.lang.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 java.lang.String getLongOptPrefix()
Gets the 'longOptPrefix'.- Returns:
- the 'longOptPrefix'
-
getLongOptSeparator
public java.lang.String getLongOptSeparator()
Gets the separator displayed between a long option and its value.- Returns:
- the separator
- Since:
- 1.3
-
getNewLine
public java.lang.String getNewLine()
Gets the 'newLine'.- Returns:
- the 'newLine'
-
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
-
getOptPrefix
public java.lang.String getOptPrefix()
Gets the 'optPrefix'.- Returns:
- the 'optPrefix'
-
getSyntaxPrefix
public java.lang.String getSyntaxPrefix()
Gets the 'syntaxPrefix'.- Returns:
- the 'syntaxPrefix'
-
getWidth
public int getWidth()
Gets the 'width'.- Returns:
- the 'width'
-
printHelp
public void printHelp(int width, java.lang.String cmdLineSyntax, java.lang.String header, Options options, java.lang.String footer)
Print the help foroptions
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 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, java.lang.String cmdLineSyntax, java.lang.String header, Options options, java.lang.String footer, boolean autoUsage)
Print the help foroptions
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 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(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 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:
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 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:
java.lang.IllegalStateException
- if there is no room to print a line
-
printHelp
public void printHelp(java.lang.String cmdLineSyntax, Options options)
Print the help foroptions
with the specified command line syntax. This method prints help information to System.out.- Parameters:
cmdLineSyntax
- the syntax for this applicationoptions
- the Options instance
-
printHelp
public void printHelp(java.lang.String cmdLineSyntax, Options options, boolean autoUsage)
Print the help foroptions
with the specified command line syntax. This method prints help information to System.out.- Parameters:
cmdLineSyntax
- the syntax for this applicationoptions
- the Options instanceautoUsage
- 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 foroptions
with the specified command line syntax. This method prints help information to System.out.- 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(java.lang.String cmdLineSyntax, java.lang.String header, Options options, java.lang.String footer, boolean autoUsage)
Print the help foroptions
with the specified command line syntax. This method prints help information to System.out.- 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
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 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
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 towidth
- The number of characters per line for the usage statement.cmdLineSyntax
- The usage statement.
-
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 statementwidth
- The number of characters to display per lineapp
- The application nameoptions
- The command line Options
-
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 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
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 towidth
- The number of characters to display per linetext
- 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 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 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 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.
-
renderWrappedTextBlock
private java.lang.Appendable renderWrappedTextBlock(java.lang.StringBuffer sb, int width, int nextLineTabStop, java.lang.String text)
Render the specified text width a maximum width. This method differs from renderWrappedText by not removing leading spaces after a new line.- 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.
-
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
-
setArgName
public void setArgName(java.lang.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(java.lang.String prefix)
Sets the 'longOptPrefix'.- Parameters:
prefix
- the new value of '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
-
setNewLine
public void setNewLine(java.lang.String newline)
Sets the 'newLine'.- Parameters:
newline
- the new value of 'newLine'
-
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
- theComparator
to use for sorting the options- Since:
- 1.2
-
setOptPrefix
public void setOptPrefix(java.lang.String prefix)
Sets the 'optPrefix'.- Parameters:
prefix
- the new value of 'optPrefix'
-
setSyntaxPrefix
public void setSyntaxPrefix(java.lang.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'
-
-