org.apache.commons.cli
Class HelpFormatter

java.lang.Object
  extended by org.apache.commons.cli.HelpFormatter

public class HelpFormatter
extends Object

A formatter of help messages for the current command line options

Version:
$Revision: 751120 $, $Date: 2009-03-06 14:45:57 -0800 (Fri, 06 Mar 2009) $
Author:
Slawek Zachcial, John Keyes (john at integralsource.com)

Field Summary
static String DEFAULT_ARG_NAME
          default name for an argument
static int DEFAULT_DESC_PAD
          the number of characters of padding to be prefixed to each description line
static int DEFAULT_LEFT_PAD
          default padding to the left of each line
static String DEFAULT_LONG_OPT_PREFIX
          default prefix for long Option
static String DEFAULT_OPT_PREFIX
          default prefix for shortOpts
static String DEFAULT_SYNTAX_PREFIX
          the string to display at the beginning of the usage statement
static 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 optionComparator
          Comparator used to sort the options when they output in help text Defaults to case-insensitive alphabetical sorting by option key
 
Constructor Summary
HelpFormatter()
           
 
Method Summary
protected  String createPadding(int len)
          Return 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()
          Returns the 'argName'.
 int getDescPadding()
          Returns the 'descPadding'.
 int getLeftPadding()
          Returns the 'leftPadding'.
 String getLongOptPrefix()
          Returns the 'longOptPrefix'.
 String getNewLine()
          Returns the 'newLine'.
 Comparator getOptionComparator()
          Comparator used to sort the options when they output in help text Defaults to case-insensitive alphabetical sorting by option key
 String getOptPrefix()
          Returns the 'optPrefix'.
 String getSyntaxPrefix()
          Returns the 'syntaxPrefix'.
 int getWidth()
          Returns the 'width'.
 void printHelp(int width, String cmdLineSyntax, String header, Options options, String footer)
          Print the help for options with the specified command line syntax.
 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.
 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.
 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.
 void printHelp(String cmdLineSyntax, Options options)
          Print the help for options with the specified command line syntax.
 void printHelp(String cmdLineSyntax, Options options, boolean autoUsage)
          Print the help for options with the specified command line syntax.
 void printHelp(String cmdLineSyntax, String header, Options options, String footer)
          Print the help for options with the specified command line syntax.
 void printHelp(String cmdLineSyntax, String header, Options options, String footer, boolean autoUsage)
          Print the help for options with the specified command line syntax.
 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.
 void printUsage(PrintWriter pw, int width, String cmdLineSyntax)
          Print 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)
          Print the specified text to the specified PrintWriter.
 void printWrapped(PrintWriter pw, int width, String text)
          Print the specified text to the specified PrintWriter.
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.
protected  StringBuffer renderWrappedText(StringBuffer sb, int width, int nextLineTabStop, String text)
          Render the specified text and return the rendered Options in a StringBuffer.
protected  String rtrim(String s)
          Remove 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 setNewLine(String newline)
          Sets the 'newLine'.
 void setOptionComparator(Comparator comparator)
          Set the comparator used to sort the options when they output in help text Passing in a null parameter will set the ordering to the default mode
 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 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
the number of characters of padding 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_ARG_NAME

public static final String DEFAULT_ARG_NAME
default name for an argument

See Also:
Constant Field Values

defaultWidth

public int defaultWidth
Deprecated. Scope will be made private for next major version - use get/setWidth methods instead.
number of characters per 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


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


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


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


defaultLongOptPrefix

public String defaultLongOptPrefix
Deprecated. Scope will be made private for next major version - use get/setLongOptPrefix methods instead.
the long Opt prefix


defaultArgName

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 optionComparator
Comparator used to sort the options when they output in help text Defaults to case-insensitive alphabetical sorting by option key

Constructor Detail

HelpFormatter

public HelpFormatter()
Method Detail

setWidth

public void setWidth(int width)
Sets the 'width'.

Parameters:
width - the new value of 'width'

getWidth

public int getWidth()
Returns the 'width'.

Returns:
the 'width'

setLeftPadding

public void setLeftPadding(int padding)
Sets the 'leftPadding'.

Parameters:
padding - the new value of 'leftPadding'

getLeftPadding

public int getLeftPadding()
Returns the 'leftPadding'.

Returns:
the 'leftPadding'

setDescPadding

public void setDescPadding(int padding)
Sets the 'descPadding'.

Parameters:
padding - the new value of 'descPadding'

getDescPadding

public int getDescPadding()
Returns the 'descPadding'.

Returns:
the 'descPadding'

setSyntaxPrefix

public void setSyntaxPrefix(String prefix)
Sets the 'syntaxPrefix'.

Parameters:
prefix - the new value of 'syntaxPrefix'

getSyntaxPrefix

public String getSyntaxPrefix()
Returns the 'syntaxPrefix'.

Returns:
the 'syntaxPrefix'

setNewLine

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

Parameters:
newline - the new value of 'newLine'

getNewLine

public String getNewLine()
Returns the 'newLine'.

Returns:
the 'newLine'

setOptPrefix

public void setOptPrefix(String prefix)
Sets the 'optPrefix'.

Parameters:
prefix - the new value of 'optPrefix'

getOptPrefix

public String getOptPrefix()
Returns the 'optPrefix'.

Returns:
the 'optPrefix'

setLongOptPrefix

public void setLongOptPrefix(String prefix)
Sets the 'longOptPrefix'.

Parameters:
prefix - the new value of 'longOptPrefix'

getLongOptPrefix

public String getLongOptPrefix()
Returns the 'longOptPrefix'.

Returns:
the 'longOptPrefix'

setArgName

public void setArgName(String name)
Sets the 'argName'.

Parameters:
name - the new value of 'argName'

getArgName

public String getArgName()
Returns the 'argName'.

Returns:
the 'argName'

getOptionComparator

public Comparator getOptionComparator()
Comparator used to sort the options when they output in help text Defaults to case-insensitive alphabetical sorting by option key


setOptionComparator

public void setOptionComparator(Comparator comparator)
Set the comparator used to sort the options when they output in help text Passing in a null parameter will set the ordering to the default mode


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 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)
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
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)
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
Throws:
IllegalStateException - if there is no room to print a 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.

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

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.

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

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

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


Copyright © 2002-2009 The Apache Software Foundation. All Rights Reserved.