xbn.programs
Class UtilCommandLine

java.lang.Object
  |
  +--xbn.XBNObject
        |
        +--xbn.programs.UtilCommandLine

public class UtilCommandLine

extends XBNObject

Random functions for parsing, casting, verification and notification of values from org.apache.commons.cli.CommandLine. See org.apache.commons.cli.CommandLine.

Source code: UtilCommandLine.java

How to pass a dash in as the first character in a value (as in a negative number)?

Fields inherited from class xbn.XBNObject

bFALSE_IN_PRODUCTION, bTRUE_IN_PRODUCTION, sCNSTR, sES, sLINE_SEP

Constructor Summary

UtilCommandLine(Options o_ptions, int i_width, String s_cmdLineSyntax, String s_header, String s_footer)

UtilCommandLine(Options o_ptions, int i_width, String s_cmdLineSyntax, String s_header, String s_footer, boolean b_autoUsage)

UtilCommandLine(Options o_ptions, PrintWriter print_writer, int i_width, String s_cmdLineSyntax, String s_header, String s_footer, int i_leftPad, int i_descPad)

UtilCommandLine(Options o_ptions, PrintWriter print_writer, int i_width, String s_cmdLineSyntax, String s_header, String s_footer, int i_leftPad, int i_descPad, boolean b_autoUsage)

UtilCommandLine(Options o_ptions, String s_cmdLineSyntax)

UtilCommandLine(Options o_ptions, String s_cmdLineSyntax, boolean b_autoUsage)

UtilCommandLine(Options o_ptions, String s_cmdLineSyntax, String s_header, String s_footer)

UtilCommandLine(Options o_ptions, String s_cmdLineSyntax, String s_header, String s_footer, boolean b_autoUsage)

Method Summary

void	crash() Stop execution, and print out usage.
void	crash(String s_error) Stop execution, and print out usage.
boolean	getAutoUsage() Get the auto-usage value, exactly as provided to the constructor.
String	getCmdLineSyntax() Get the command-line syntax string, exactly as provided to the constructor.
CommandLine	getCommandLine() Get the CommandLine, as previously parsed.
CommandLine	getCommandLine(String[] as_cmdLineParams) Get the CommandLine after parsing the actually-provided command line.
CommandLine	getCommandLine(String[] as_cmdLineParams, CommandLineParser cmd_linePrsr) Get the CommandLine after parsing the actually-provided command line.
int	getDescPad() Get the description-pad value, exactly as provided to the constructor.
String	getFooter() Get the footer string, exactly as provided to the constructor.
String	getHeader() Get the header string, exactly as provided to the constructor.
int	getInt(String s_optionName) Get the int value of a parameter.
int	getInt(String s_optionName, boolean b_useDefaultValue, int i_defaultValue, RangeConfig range_config) Get the int value of a parameter.
int	getInt(String s_optionName, int i_defaultValue) Get the int value of a parameter.
int	getInt(String s_optionName, int i_defaultValue, RangeConfig range_config) Get the int value of a parameter, which must conform to a range.
int	getInt(String s_optionName, RangeConfig range_config) Get the int value of a parameter, which must conform to a range.
int	getLeftPad() Get the left-pad value, exactly as provided to the constructor.
Options	getOptions() Get the Options, exactly as provided to the constructor.
Outputter	getOSDOOrOSDOAndFile(String s_optionName) Get an Outputter to write to screen only, or both to screen and file.
Outputter	getOSDOOrOSDOAndFile(String s_optionName, boolean b_appendToFile) Get an Outputter to write to screen only, or both to screen and file.
PrintWriter	getPrintWriter() Get the PrintWriter, exactly as provided to the constructor.
int	getWidth() Get the width value, exactly as provided to the constructor.
void	printHelp() Print out the usage string.
void	printHelp(String s_error) Print out the usage string, plus an optional error message.

Methods inherited from class xbn.XBNObject

getXMsgPrefix, sop, sopl, sopl, throwAX, throwAXIfBadStr, throwAXIfNull, throwAXSpoof

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UtilCommandLine

public UtilCommandLine(Options o_ptions,
                       String s_cmdLineSyntax)

UtilCommandLine

public UtilCommandLine(Options o_ptions,
                       String s_cmdLineSyntax,
                       boolean b_autoUsage)

UtilCommandLine

public UtilCommandLine(Options o_ptions,
                       String s_cmdLineSyntax,
                       String s_header,
                       String s_footer)

UtilCommandLine

public UtilCommandLine(Options o_ptions,
                       String s_cmdLineSyntax,
                       String s_header,
                       String s_footer,
                       boolean b_autoUsage)

UtilCommandLine

public UtilCommandLine(Options o_ptions,
                       int i_width,
                       String s_cmdLineSyntax,
                       String s_header,
                       String s_footer)

UtilCommandLine

public UtilCommandLine(Options o_ptions,
                       int i_width,
                       String s_cmdLineSyntax,
                       String s_header,
                       String s_footer,
                       boolean b_autoUsage)

UtilCommandLine

public UtilCommandLine(Options o_ptions,
                       PrintWriter print_writer,
                       int i_width,
                       String s_cmdLineSyntax,
                       String s_header,
                       String s_footer,
                       int i_leftPad,
                       int i_descPad)

UtilCommandLine

public UtilCommandLine(Options o_ptions,
                       PrintWriter print_writer,
                       int i_width,
                       String s_cmdLineSyntax,
                       String s_header,
                       String s_footer,
                       int i_leftPad,
                       int i_descPad,
                       boolean b_autoUsage)

Method Detail

getCommandLine

public final CommandLine getCommandLine(String[] as_cmdLineParams)

Get the CommandLine after parsing the actually-provided command line.

Returns:

getCommandLine(as_cmdLineParams, (new BasicParser()))

getCommandLine

public final CommandLine getCommandLine(String[] as_cmdLineParams,
                                        CommandLineParser cmd_linePrsr)

Get the CommandLine after parsing the actually-provided command line.

In order, this first outputs the actually-provided command line, parses the actually-provided command line (and crashes with the usage message if anything is wrong), and then returns the derived CommandLine, as returned by cmd_linePrsr.parse().

This should only be called once. Second and subsequent requests for the CommandLine object should use getCommandLine instead.

Parameters:

as_cmdLineParams - The array of command line parameters, provided directly from the 'main' function in your application. May not be null.

cmd_linePrsr - The CommandLineParser. May not be null.

getCommandLine

public final CommandLine getCommandLine()

Get the CommandLine, as previously parsed. (as_cmdLineParams, cmd_linePrsr) must be called before this using this function.

Returns:

The CommandLine as originally generated by the two-parameter version of this function.

getPrintWriter

public final PrintWriter getPrintWriter()

Get the PrintWriter, exactly as provided to the constructor.

getWidth

public final int getWidth()

Get the width value, exactly as provided to the constructor.

getCmdLineSyntax

public final String getCmdLineSyntax()

Get the command-line syntax string, exactly as provided to the constructor.

getHeader

public final String getHeader()

Get the header string, exactly as provided to the constructor.

getOptions

public final Options getOptions()

Get the Options, exactly as provided to the constructor.

getLeftPad

public final int getLeftPad()

Get the left-pad value, exactly as provided to the constructor.

getDescPad

public final int getDescPad()

Get the description-pad value, exactly as provided to the constructor.

getFooter

public final String getFooter()

Get the footer string, exactly as provided to the constructor.

getAutoUsage

public final boolean getAutoUsage()

Get the auto-usage value, exactly as provided to the constructor.

crash

public final void crash()

Stop execution, and print out usage.

Equal to printHelp(null)

crash

public final void crash(String s_error)

Stop execution, and print out usage. If an error message is provided, print it out, too (and first).

printHelp

public final void printHelp()

Print out the usage string.

Equal to printHelp(null)

printHelp

public final void printHelp(String s_error)

Print out the usage string, plus an optional error message.

Depending on the constructor signature use, that (similar) version of the [HelpFormatter].printHelp function is used.

Parameters:

s_error - A specific error message, if appropriate. If null, then no specific error message is output. If non-null, then this is printed out immediately before the usage message.

getOSDOOrOSDOAndFile

public final Outputter getOSDOOrOSDOAndFile(String s_optionName)

Get an Outputter to write to screen only, or both to screen and file.

Returns:

getOSDOOrOSDOAndFile(s_optionName, true)

getOSDOOrOSDOAndFile

public final Outputter getOSDOOrOSDOAndFile(String s_optionName,
                                            boolean b_appendToFile)

Get an Outputter to write to screen only, or both to screen and file.

Parameters:

s_optionName - The name of the parameter. If this parameter is provided, then it must have an argument, and that argument must be a legal (writeable and optionally existing) file name.

Returns:

If getCommandLine().hasOption(s_optionName): new Outputter(new OWSDOAndFile(getCommandLine().getOptionValue(s_optionName), b_appendToFile))
Otherwise, return new OSysDotOut()

getInt

public final int getInt(String s_optionName)

Get the int value of a parameter.

Returns:

getInt(s_optionName, false, -1, (new RangeConfig()))

getInt

public final int getInt(String s_optionName,
                        int i_defaultValue)

Get the int value of a parameter. If the parameter was not provided, use an alternate default value.

Returns:

getInt(s_optionName, true, i_defaultValue, (new RangeConfig()))

getInt

public final int getInt(String s_optionName,
                        RangeConfig range_config)

Get the int value of a parameter, which must conform to a range.

Returns:

getInt(s_optionName, false, -1, range_config)

getInt

public final int getInt(String s_optionName,
                        int i_defaultValue,
                        RangeConfig range_config)

Get the int value of a parameter, which must conform to a range. If the parameter was not provided, use an alternate default value.

Returns:

getInt(s_optionName, true, i_defaultValue, range_config)

getInt

public final int getInt(String s_optionName,
                        boolean b_useDefaultValue,
                        int i_defaultValue,
                        RangeConfig range_config)

Get the int value of a parameter.

Parameters:

s_optionName - The name of the desired parameter, which must have an argument. The value of the argument must be a legal int, acording to Integer.valueOf.

b_useDefaultValue - If true, then if the parameter was not provided on the command line, return i_defaultValue instead.

i_defaultValue - The default value to return, when the parameter is not provided. Ignored when b_useDefaultValue is false. Ignored when b_useDefaultValue is true, and this parameter was provided. When not ignored, must conform to range_config.isValid.

range_config - The range that the value must conform to.