org.apache.commons.cli

Class HelpFormatter

public class HelpFormatter extends Object

A formatter of help messages for the current command line options

Author: Slawek Zachcial John Keyes (john at integralsource.com)

Nested Class Summary
static classHelpFormatter.OptionComparator

This class implements the Comparator interface for comparing Options.

Field Summary
StringdefaultArgName
the name of the argument
intdefaultDescPad
the number of characters of padding to be prefixed to each description line
intdefaultLeftPad
amount of padding to the left of each line
StringdefaultLongOptPrefix
the long Opt prefix
StringdefaultNewLine
the new line string
StringdefaultOptPrefix
the shortOpt prefix
StringdefaultSyntaxPrefix
the string to display at the begining of the usage statement
intdefaultWidth
number of characters per line
static StringDEFAULT_ARG_NAME
default name for an argument
static intDEFAULT_DESC_PAD
the number of characters of padding to be prefixed to each description line
static intDEFAULT_LEFT_PAD
default padding to the left of each line
static StringDEFAULT_LONG_OPT_PREFIX
default prefix for long Option
static StringDEFAULT_OPT_PREFIX
default prefix for shortOpts
static StringDEFAULT_SYNTAX_PREFIX
the string to display at the begining of the usage statement
static intDEFAULT_WIDTH
default number of characters per line
Method Summary
static voidappendOption(StringBuffer buff, Option option, boolean required)
Appends the usage clause for an Option to a StringBuffer.
static voidappendOptionGroup(StringBuffer buff, OptionGroup group)
Appends the usage clause for an OptionGroup to a StringBuffer.
protected StringcreatePadding(int len)

Return a String of padding of length len.

protected intfindWrapPos(String text, int width, int startPos)
Finds the next text wrap position after startPos for the text in text with the column width width.
StringgetArgName()
Returns the 'argName'.
intgetDescPadding()
Returns the 'descPadding'.
intgetLeftPadding()
Returns the 'leftPadding'.
StringgetLongOptPrefix()
Returns the 'longOptPrefix'.
StringgetNewLine()
Returns the 'newLine'.
StringgetOptPrefix()
Returns the 'optPrefix'.
StringgetSyntaxPrefix()
Returns the 'syntaxPrefix'.
intgetWidth()
Returns the 'width'.
voidprintHelp(String cmdLineSyntax, Options options)

Print the help for options with the specified command line syntax.

voidprintHelp(String cmdLineSyntax, Options options, boolean autoUsage)

Print the help for options with the specified command line syntax.

voidprintHelp(String cmdLineSyntax, String header, Options options, String footer)

Print the help for options with the specified command line syntax.

voidprintHelp(String cmdLineSyntax, String header, Options options, String footer, boolean autoUsage)

Print the help for options with the specified command line syntax.

voidprintHelp(int width, String cmdLineSyntax, String header, Options options, String footer)

Print the help for options with the specified command line syntax.

voidprintHelp(int width, String cmdLineSyntax, String header, Options options, String footer, boolean autoUsage)

Print the help for options with the specified command line syntax.

voidprintHelp(PrintWriter pw, int width, String cmdLineSyntax, String header, Options options, int leftPad, int descPad, String footer)

Print the help for options with the specified command line syntax.

voidprintHelp(PrintWriter pw, int width, String cmdLineSyntax, String header, Options options, int leftPad, int descPad, String footer, boolean autoUsage)

Print the help for options with the specified command line syntax.

voidprintOptions(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.

voidprintUsage(PrintWriter pw, int width, String app, Options options)

Prints the usage statement for the specified application.

voidprintUsage(PrintWriter pw, int width, String cmdLineSyntax)

Print the cmdLineSyntax to the specified writer, using the specified width.

voidprintWrapped(PrintWriter pw, int width, String text)

Print the specified text to the specified PrintWriter.

voidprintWrapped(PrintWriter pw, int width, int nextLineTabStop, String text)

Print the specified text to the specified PrintWriter.

protected StringBufferrenderOptions(StringBuffer sb, int width, Options options, int leftPad, int descPad)

Render the specified Options and return the rendered Options in a StringBuffer.

protected StringBufferrenderWrappedText(StringBuffer sb, int width, int nextLineTabStop, String text)

Render the specified text and return the rendered Options in a StringBuffer.

protected Stringrtrim(String s)

Remove the trailing whitespace from the specified String.

voidsetArgName(String name)
Sets the 'argName'.
voidsetDescPadding(int padding)
Sets the 'descPadding'.
voidsetLeftPadding(int padding)
Sets the 'leftPadding'.
voidsetLongOptPrefix(String prefix)
Sets the 'longOptPrefix'.
voidsetNewLine(String newline)
Sets the 'newLine'.
voidsetOptPrefix(String prefix)
Sets the 'optPrefix'.
voidsetSyntaxPrefix(String prefix)
Sets the 'syntaxPrefix'.
voidsetWidth(int width)
Sets the 'width'.

Field Detail

defaultArgName

public String defaultArgName

Deprecated: Scope will be made private for next major version - use get/setArgName methods instead.

the name of the argument

defaultDescPad

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

defaultLeftPad

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

defaultLongOptPrefix

public String defaultLongOptPrefix

Deprecated: Scope will be made private for next major version - use get/setLongOptPrefix methods instead.

the long Opt prefix

defaultNewLine

public String defaultNewLine

Deprecated: Scope will be made private for next major version - use get/setNewLine methods instead.

the new line string

defaultOptPrefix

public String defaultOptPrefix

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

the shortOpt prefix

defaultSyntaxPrefix

public String defaultSyntaxPrefix

Deprecated: Scope will be made private for next major version - use get/setSyntaxPrefix methods instead.

the string to display at the begining of the usage statement

defaultWidth

public int defaultWidth

Deprecated: Scope will be made private for next major version - use get/setWidth methods instead.

number of characters per line

DEFAULT_ARG_NAME

public static final String DEFAULT_ARG_NAME
default name for an argument

DEFAULT_DESC_PAD

public static final int DEFAULT_DESC_PAD
the number of characters of padding to be prefixed to each description line

DEFAULT_LEFT_PAD

public static final int DEFAULT_LEFT_PAD
default padding to the left of each line

DEFAULT_LONG_OPT_PREFIX

public static final String DEFAULT_LONG_OPT_PREFIX
default prefix for long Option

DEFAULT_OPT_PREFIX

public static final String DEFAULT_OPT_PREFIX
default prefix for shortOpts

DEFAULT_SYNTAX_PREFIX

public static final String DEFAULT_SYNTAX_PREFIX
the string to display at the begining of the usage statement

DEFAULT_WIDTH

public static final int DEFAULT_WIDTH
default number of characters per line

Method Detail

appendOption

private static void appendOption(StringBuffer buff, Option option, boolean required)
Appends the usage clause for an Option to a StringBuffer.

Parameters: buff the StringBuffer to append to option the Option to append required whether the Option is required or not

appendOptionGroup

private static void appendOptionGroup(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 to group the group to append

See Also: HelpFormatter

createPadding

protected 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

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 postion before startPos+width having a whitespace character (space, \n, \r).

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: postion on which the text must be wrapped or -1 if the wrap position is at the end of the text

getArgName

public String getArgName()
Returns the 'argName'.

Returns: the 'argName'

getDescPadding

public int getDescPadding()
Returns the 'descPadding'.

Returns: the 'descPadding'

getLeftPadding

public int getLeftPadding()
Returns the 'leftPadding'.

Returns: the 'leftPadding'

getLongOptPrefix

public String getLongOptPrefix()
Returns the 'longOptPrefix'.

Returns: the 'longOptPrefix'

getNewLine

public String getNewLine()
Returns the 'newLine'.

Returns: the 'newLine'

getOptPrefix

public String getOptPrefix()
Returns the 'optPrefix'.

Returns: the 'optPrefix'

getSyntaxPrefix

public String getSyntaxPrefix()
Returns the 'syntaxPrefix'.

Returns: the 'syntaxPrefix'

getWidth

public int getWidth()
Returns the 'width'.

Returns: the 'width'

printHelp

public void printHelp(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(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(String cmdLineSyntax, String header, Options options, 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 begining 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)

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 begining 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, String cmdLineSyntax, String header, Options options, 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 begining 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)

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 begining 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)

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

printHelp

public void printHelp(PrintWriter pw, int width, String cmdLineSyntax, String header, Options options, int leftPad, int descPad, 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 begining 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

printOptions

public void printOptions(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

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

printUsage

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

printWrapped

public void printWrapped(PrintWriter pw, int width, 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(PrintWriter pw, int width, int nextLineTabStop, 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 StringBuffer renderOptions(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 StringBuffer renderWrappedText(StringBuffer sb, int width, int nextLineTabStop, 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.

rtrim

protected String rtrim(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(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'

setNewLine

public void setNewLine(String newline)
Sets the 'newLine'.

Parameters: newline the new value of 'newLine'

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'