org.apache.commons.cli

Class HelpFormatter

java.lang.Object

org.apache.commons.cli.HelpFormatter

Deprecated.

Use HelpFormatter.

@Deprecated
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
 

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	HelpFormatter.Builder	Deprecated. Builds HelpFormatter.

Field Summary

Fields

Modifier and Type	Field	Description
static String	DEFAULT_ARG_NAME	Deprecated. Default name for an argument
static int	DEFAULT_DESC_PAD	Deprecated. Number of space characters to be prefixed to each description line
static int	DEFAULT_LEFT_PAD	Deprecated. Default padding to the left of each line
static String	DEFAULT_LONG_OPT_PREFIX	Deprecated. Default prefix for long Option
static String	DEFAULT_LONG_OPT_SEPARATOR	Deprecated. Default separator displayed between a long Option and its value
static String	DEFAULT_OPT_PREFIX	Deprecated. Default prefix for shortOpts
static String	DEFAULT_SYNTAX_PREFIX	Deprecated. The string to display at the beginning of the usage statement
static int	DEFAULT_WIDTH	Deprecated. 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<Option>	optionComparator	Deprecated. 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()	Deprecated. Constructs a new instance.

Method Summary

Modifier and Type	Method	Description
static HelpFormatter.Builder	builder()	Deprecated. Creates a new builder.
protected String	createPadding(int len)	Deprecated. Creates a String of padding of length len.
protected int	findWrapPos(String text, int width, int startPos)	Deprecated. Finds the next text wrap position after startPos for the text in text with the column width width.
String	getArgName()	Deprecated. Gets the 'argName'.
int	getDescPadding()	Deprecated. Gets the 'descPadding'.
static String	getDescription(Option option)	Deprecated. Gets the option description or an empty string if the description is null.
int	getLeftPadding()	Deprecated. Gets the 'leftPadding'.
String	getLongOptPrefix()	Deprecated. Gets the 'longOptPrefix'.
String	getLongOptSeparator()	Deprecated. Gets the separator displayed between a long option and its value.
String	getNewLine()	Deprecated. Gets the 'newLine'.
Comparator<Option>	getOptionComparator()	Deprecated. Comparator used to sort the options when they output in help text.
String	getOptPrefix()	Deprecated. Gets the 'optPrefix'.
String	getSyntaxPrefix()	Deprecated. Gets the 'syntaxPrefix'.
int	getWidth()	Deprecated. Gets the 'width'.
void	printHelp(int width, String cmdLineSyntax, String header, Options options, String footer)	Deprecated. Prints the help for options with the specified command line syntax.
void	printHelp(int width, String cmdLineSyntax, String header, Options options, String footer, boolean autoUsage)	Deprecated. Prints 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)	Deprecated. Prints 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)	Deprecated. Prints the help for options with the specified command line syntax.
void	printHelp(String cmdLineSyntax, Options options)	Deprecated. Prints the help for options with the specified command line syntax.
void	printHelp(String cmdLineSyntax, Options options, boolean autoUsage)	Deprecated. Prints the help for options with the specified command line syntax.
void	printHelp(String cmdLineSyntax, String header, Options options, String footer)	Deprecated. Prints the help for options with the specified command line syntax.
void	printHelp(String cmdLineSyntax, String header, Options options, String footer, boolean autoUsage)	Deprecated. Prints the help for options with the specified command line syntax.
void	printOptions(PrintWriter pw, int width, Options options, int leftPad, int descPad)	Deprecated. 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)	Deprecated. Prints the cmdLineSyntax to the specified writer, using the specified width.
void	printUsage(PrintWriter pw, int width, String app, Options options)	Deprecated. Prints the usage statement for the specified application.
void	printWrapped(PrintWriter pw, int width, int nextLineTabStop, String text)	Deprecated. Prints the specified text to the specified PrintWriter.
void	printWrapped(PrintWriter pw, int width, String text)	Deprecated. Prints the specified text to the specified PrintWriter.
protected StringBuffer	renderOptions(StringBuffer sb, int width, Options options, int leftPad, int descPad)	Deprecated. Renders the specified Options and return the rendered Options in a StringBuffer.
protected StringBuffer	renderWrappedText(StringBuffer sb, int width, int nextLineTabStop, String text)	Deprecated. Renders the specified text and return the rendered Options in a StringBuffer.
protected String	rtrim(String s)	Deprecated. Removes the trailing whitespace from the specified String.
void	setArgName(String name)	Deprecated. Sets the 'argName'.
void	setDescPadding(int padding)	Deprecated. Sets the 'descPadding'.
void	setLeftPadding(int padding)	Deprecated. Sets the 'leftPadding'.
void	setLongOptPrefix(String prefix)	Deprecated. Sets the 'longOptPrefix'.
void	setLongOptSeparator(String longOptSeparator)	Deprecated. Sets the separator displayed between a long option and its value.
void	setNewLine(String newline)	Deprecated. Sets the 'newLine'.
void	setOptionComparator(Comparator<Option> comparator)	Deprecated. Sets the comparator used to sort the options when they output in help text.
void	setOptPrefix(String prefix)	Deprecated. Sets the 'optPrefix'.
void	setSyntaxPrefix(String prefix)	Deprecated. Sets the 'syntaxPrefix'.
void	setWidth(int width)	Deprecated. 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

Deprecated.

Default number of characters per line

See Also:

Constant Field Values

DEFAULT_LEFT_PAD

public static final int DEFAULT_LEFT_PAD

Deprecated.

Default padding to the left of each line

See Also:

Constant Field Values

DEFAULT_DESC_PAD

public static final int DEFAULT_DESC_PAD

Deprecated.

Number of space characters to be prefixed to each description line

See Also:

Constant Field Values

DEFAULT_SYNTAX_PREFIX

public static final String DEFAULT_SYNTAX_PREFIX

Deprecated.

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

Deprecated.

Default prefix for shortOpts

See Also:

Constant Field Values

DEFAULT_LONG_OPT_PREFIX

public static final String DEFAULT_LONG_OPT_PREFIX

Deprecated.

Default prefix for long Option

See Also:

Constant Field Values

DEFAULT_LONG_OPT_SEPARATOR

public static final String DEFAULT_LONG_OPT_SEPARATOR

Deprecated.

Default separator displayed between a long Option and its value

Since:

1.3

See Also:

Constant Field Values

DEFAULT_ARG_NAME

public static final String DEFAULT_ARG_NAME

Deprecated.

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 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 String defaultNewLine

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

The new line string

defaultOptPrefix

@Deprecated
public String defaultOptPrefix

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

The shortOpt prefix

defaultLongOptPrefix

@Deprecated
public String defaultLongOptPrefix

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

The long Opt prefix

defaultArgName

@Deprecated
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<Option> optionComparator

Deprecated.

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

Deprecated.

Constructs a new instance.

Method Detail

builder

public static HelpFormatter.Builder builder()

Deprecated.

Creates a new builder.

Returns:

a new builder.

Since:

1.7.0

getDescription

public static String getDescription(Option option)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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

Deprecated.

Gets the 'argName'.

Returns:

the 'argName'

getDescPadding

public int getDescPadding()

Deprecated.

Gets the 'descPadding'.

Returns:

the 'descPadding'

getLeftPadding

public int getLeftPadding()

Deprecated.

Gets the 'leftPadding'.

Returns:

the 'leftPadding'

getLongOptPrefix

public String getLongOptPrefix()

Deprecated.

Gets the 'longOptPrefix'.

Returns:

the 'longOptPrefix'

getLongOptSeparator

public String getLongOptSeparator()

Deprecated.

Gets the separator displayed between a long option and its value.

Returns:

the separator

Since:

1.3

getNewLine

public String getNewLine()

Deprecated.

Gets the 'newLine'.

Returns:

the 'newLine'

getOptionComparator

public Comparator<Option> getOptionComparator()

Deprecated.

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

Deprecated.

Gets the 'optPrefix'.

Returns:

the 'optPrefix'

getSyntaxPrefix

public String getSyntaxPrefix()

Deprecated.

Gets the 'syntaxPrefix'.

Returns:

the 'syntaxPrefix'

getWidth

public int getWidth()

Deprecated.

Gets the 'width'.

Returns:

the 'width'

printHelp

public void printHelp(int width,
                      String cmdLineSyntax,
                      String header,
                      Options options,
                      String footer)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

Sets the 'argName'.

Parameters:

name - the new value of 'argName'

setDescPadding

public void setDescPadding(int padding)

Deprecated.

Sets the 'descPadding'.

Parameters:

padding - the new value of 'descPadding'

setLeftPadding

public void setLeftPadding(int padding)

Deprecated.

Sets the 'leftPadding'.

Parameters:

padding - the new value of 'leftPadding'

setLongOptPrefix

public void setLongOptPrefix(String prefix)

Deprecated.

Sets the 'longOptPrefix'.

Parameters:

prefix - the new value of 'longOptPrefix'

setLongOptSeparator

public void setLongOptSeparator(String longOptSeparator)

Deprecated.

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)

Deprecated.

Sets the 'newLine'.

Parameters:

newline - the new value of 'newLine'

setOptionComparator

public void setOptionComparator(Comparator<Option> comparator)

Deprecated.

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)

Deprecated.

Sets the 'optPrefix'.

Parameters:

prefix - the new value of 'optPrefix'

setSyntaxPrefix

public void setSyntaxPrefix(String prefix)

Deprecated.

Sets the 'syntaxPrefix'.

Parameters:

prefix - the new value of 'syntaxPrefix'

setWidth

public void setWidth(int width)

Deprecated.

Sets the 'width'.

Parameters:

width - the new value of 'width'