com.Ostermiller.util
Class CmdLn

java.lang.Object
  com.Ostermiller.util.CmdLn

public final class CmdLn
extends Object

Command line argument parser for Java command line programs. More information about this class and code samples for suggested use are available from ostermiller.org.

Since:

ostermillerutils 1.07.00

Constructor Summary

CmdLn(String[] arguments)
New command line options with the given command line arguments

Method Summary

CmdLn	addOption(CmdLnOption option) Add option.
CmdLn	addOptions(CmdLnOption[] options) Add options.
CmdLn	addOptions(Collection<CmdLnOption> options) Add options.
String	getHelp() Print help for the command line options.
String	getHelp(int indent, int width) Print help for the command line options.
List<String>	getNonOptionArguments() Get the left over arguments -- the arguments that are not associated with any arguments.
CmdLnResult	getResult(char c) Get the last result associated with the given argument.
CmdLnResult	getResult(Character c) Get the last result associated with the given argument.
CmdLnResult	getResult(CmdLnOption option) Get the last result associated with the option.
CmdLnResult	getResult(String s) Get the last result associated with the given argument.
List<CmdLnResult>	getResults() Get all the results in the order in which they appear in the command line.
List<CmdLnResult>	getResults(char c) Get all the results associated with the given argument in the order in which they appear in the command line.
List<CmdLnResult>	getResults(Character c) Get all the results associated with the given argument in the order in which they appear in the command line.
List<CmdLnResult>	getResults(CmdLnOption option) Get all the results associated with the given argument in the order in which they appear in the command line.
List<CmdLnResult>	getResults(String s) Get all the results associated with the given argument in the order in which they appear in the command line.
int	occurrences(char c) The number of times the specified option is present in the command line.
int	occurrences(Character c) The number of times the specified option is present in the command line.
int	occurrences(CmdLnOption option) The number of times the specified option is present in the command line.
int	occurrences(String s) The number of times the specified option is present in the command line.
void	parse() Parse the command line options if they have not already been parsed.
boolean	present(char c) Whether or not the specified option is present in the command line.
boolean	present(Character c) Whether or not the specified option is present in the command line.
boolean	present(CmdLnOption option) Whether or not the specified option is present in the command line.
boolean	present(String s) Whether or not the specified option is present in the command line.
void	printHelp() Print help for the command line options to standard output.
void	printHelp(int indent, int width) Print help for the command line options to standard output.
void	printHelp(OutputStream out) Print help for the command line options.
void	printHelp(OutputStream out, int indent, int width) Print help for the command line options.
void	printHelp(PrintWriter out) Print help for the command line options.
void	printHelp(PrintWriter out, int indent, int width) Print help for the command line options.
void	printHelp(Writer out) Print help for the command line options.
void	printHelp(Writer out, int indent, int width) Print help for the command line options.
CmdLn	setDescription(String description) Set the description for the program.
CmdLn	setNonOptionSeparators(String[] nonOptionSeparators) Set the "stop" option that causes any following arguments to be treated as non-option arguments, even if they look like an option.
CmdLn	setOptionArgumentDelimiters(char[] delimiters) Set the delimiters that separate a option name from a value within a single argument.
CmdLn	setOptionStarts(String[] longOptionsStart, String[] shortOptionsStart) Set what long options and short options start with.
CmdLn	setOptionStarts(String longOptionsStart, String shortOptionsStart) Set what long options and short options start with.

Methods inherited from class java.lang.Object

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

Constructor Detail

CmdLn

public CmdLn(String[] arguments)

New command line options with the given command line arguments

Parameters:

arguments - command line arguments from main method

Since:

ostermillerutils 1.07.00

Method Detail

setOptionArgumentDelimiters

public CmdLn setOptionArgumentDelimiters(char[] delimiters)

Set the delimiters that separate a option name from a value within a single argument. This is to support arguments of the form "--name=value". The equals sign can separate the option name ("name") from the option argument ("value"). By default, the delimiters are '=', ':', and ' '.

Parameters:

delimiters - list of delimiters

Returns:

this for method chaining.

Since:

ostermillerutils 1.07.00

setOptionStarts

public CmdLn setOptionStarts(String longOptionsStart,
                             String shortOptionsStart)

Set what long options and short options start with. Typically long options start with "--" and short options with "-" (this is the default).

Parameters:

longOptionsStart - What long options start with (default "--") or null for no long options;

shortOptionsStart - What short options start with (default "-") or null for no short options;

Returns:

this for method chaining

Throws:

IllegalArgumentException - if the long or short start is the empty string

Since:

ostermillerutils 1.07.00

setOptionStarts

public CmdLn setOptionStarts(String[] longOptionsStart,
                             String[] shortOptionsStart)

Set what long options and short options start with. Typically long options start with "--" and short options with "-" and this is the default.

The first option start in each array will be the canonical option start that is used in the help message.

Parameters:

longOptionsStart - What long options start with (default "--") or null or empty for no long options;

shortOptionsStart - What short options start with (default "-") or null or empty for no short options;

Returns:

this for method chaining

Throws:

IllegalArgumentException - if the long or short start is the empty string

Since:

ostermillerutils 1.07.00

setNonOptionSeparators

public CmdLn setNonOptionSeparators(String[] nonOptionSeparators)

Set the "stop" option that causes any following arguments to be treated as non-option arguments, even if they look like an option.

The default non-option separator is "--".

Parameters:

nonOptionSeparators - List of arguments that stop processing options and treat remaining arguments as non option arguments.

Returns:

this for method chaining

Since:

ostermillerutils 1.07.00

setDescription

public CmdLn setDescription(String description)

Set the description for the program. This description will be printed on the first line of the help message.

Parameters:

description - short description about the program

Returns:

this for method chaining

Since:

ostermillerutils 1.07.00

addOptions

public CmdLn addOptions(Collection<CmdLnOption> options)

Add options.

Parameters:

options - options to be added.

Returns:

this for method chaining

Throws:

NullPointerException - if the options are null.

NullPointerException - if any option in the collection is null.

IllegalStateException - if the command line has already been parsed.

Since:

ostermillerutils 1.07.00

addOptions

public CmdLn addOptions(CmdLnOption[] options)

Add options.

Parameters:

options - options to be added.

Returns:

this for method chaining

Throws:

NullPointerException - if the options are null.

NullPointerException - if any option in the collection is null.

IllegalStateException - if the command line has already been parsed.

Since:

ostermillerutils 1.07.00

addOption

public CmdLn addOption(CmdLnOption option)

Add option.

Parameters:

option - option to be added.

Returns:

this for method chaining

Throws:

NullPointerException - if the option is null.

IllegalStateException - if the command line has already been parsed.

Since:

ostermillerutils 1.07.00

getResult

public CmdLnResult getResult(String s)

Get the last result associated with the given argument. If a option is in the command line multiple times, typically the last one should be the one that wins as an override mechanism. Parses the command line if not already parsed.

Parameters:

s - long argument

Returns:

result for argument, or null if not associated with an option or not present in the command line.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

getResult

public CmdLnResult getResult(Character c)

Get the last result associated with the given argument. If a option is in the command line multiple times, typically the last one should be the one that wins as an override mechanism. Parses the command line if not already parsed.

Parameters:

c - short argument

Returns:

result for argument, or null if not associated with an option or not present in the command line.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

getResult

public CmdLnResult getResult(char c)

Get the last result associated with the given argument. If a option is in the command line multiple times, typically the last one should be the one that wins as an override mechanism. Parses the command line if not already parsed.

Parameters:

c - short argument

Returns:

result for argument, or null if not associated with an option or not present in the command line.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

getResult

public CmdLnResult getResult(CmdLnOption option)

Get the last result associated with the option. If a option is in the command line multiple times, typically the last one should be the one that wins as an override mechanism. Parses the command line if not already parsed.

Parameters:

option - command line option

Returns:

result for argument, or null if option not added to this command line or not present in the command line.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

getResults

public List<CmdLnResult> getResults()

Get all the results in the order in which they appear in the command line. Parses the command line if not already parsed.

Returns:

unmodifiable list of all options and arguments that were specified on the command line

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

getResults

public List<CmdLnResult> getResults(String s)

Get all the results associated with the given argument in the order in which they appear in the command line. If a option is in the command line multiple times, typically the last one should be the one that wins as an override mechanism, however it may sometimes be useful to know about all of them. Parses the command line if not already parsed.

Parameters:

s - long argument

Returns:

results for argument, or null if not associated with an option or not present in the command line.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

getResults

public List<CmdLnResult> getResults(Character c)

Get all the results associated with the given argument in the order in which they appear in the command line. If a option is in the command line multiple times, typically the last one should be the one that wins as an override mechanism, however it may sometimes be useful to know about all of them. Parses the command line if not already parsed.

Parameters:

c - short argument

Returns:

results for argument, or null if not associated with an option or not present in the command line.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

Since:

ostermillerutils 1.07.00

getResults

public List<CmdLnResult> getResults(char c)

Get all the results associated with the given argument in the order in which they appear in the command line. If a option is in the command line multiple times, typically the last one should be the one that wins as an override mechanism, however it may sometimes be useful to know about all of them. Parses the command line if not already parsed.

Parameters:

c - short argument

Returns:

results for argument, or null if not associated with an option or not present in the command line.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

getResults

public List<CmdLnResult> getResults(CmdLnOption option)

Get all the results associated with the given argument in the order in which they appear in the command line. If a option is in the command line multiple times, typically the last one should be the one that wins as an override mechanism, however it may sometimes be useful to know about all of them. Parses the command line if not already parsed.

Parameters:

option - command line option

Returns:

results for option, or null if option not added to this command line or not present in the command line.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

present

public boolean present(String s)

Whether or not the specified option is present in the command line. Parses the command line if not already parsed.

Parameters:

s - long argument

Returns:

true iff the option (or its synonyms) is present.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

present

public boolean present(Character c)

Whether or not the specified option is present in the command line. Parses the command line if not already parsed.

Parameters:

c - short argument

Returns:

true iff the option (or its synonyms) is present.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

present

public boolean present(char c)

Whether or not the specified option is present in the command line. Parses the command line if not already parsed.

Parameters:

c - short argument

Returns:

true iff the option (or its synonyms) is present.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

present

public boolean present(CmdLnOption option)

Whether or not the specified option is present in the command line. Parses the command line if not already parsed.

Parameters:

option - command line option

Returns:

true iff the option is present.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

occurrences

public int occurrences(String s)

The number of times the specified option is present in the command line. Parses the command line if not already parsed.

Parameters:

s - long argument

Returns:

true iff the option (or its synonyms) is present.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

occurrences

public int occurrences(Character c)

The number of times the specified option is present in the command line. Parses the command line if not already parsed.

Parameters:

c - short argument

Returns:

true iff the option (or its synonyms) is present.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

occurrences

public int occurrences(char c)

The number of times the specified option is present in the command line. Parses the command line if not already parsed.

Parameters:

c - short argument

Returns:

true iff the option (or its synonyms) is present.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

occurrences

public int occurrences(CmdLnOption option)

The number of times the specified option is present in the command line. Parses the command line if not already parsed.

Parameters:

option - command line option

Returns:

true iff the option is present.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

getNonOptionArguments

public List<String> getNonOptionArguments()

Get the left over arguments -- the arguments that are not associated with any arguments. Parses the command line if not already parsed.

Returns:

unmodifiable list of arguments

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

ExtraCmdLnArgumentException - if a command line option has too many arguments during parsing.

Since:

ostermillerutils 1.07.00

parse

public void parse()

Parse the command line options if they have not already been parsed. Process the options, run through the arguments, ensure that all the arguments are good, call any listeners.

Once this command line has been parsed, options may no longer be added.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered

MissingCmdLnArgumentException - if a command line option does not have enough arguments.

ExtraCmdLnArgumentException - if a command line option has too many arguments.

Since:

ostermillerutils 1.07.00

getHelp

public String getHelp()

Print help for the command line options. Help will be in this format:

 program description
   --argument -a   argument a description
   --another -b       argument b description
   --third -c      argument c description
 

Indentation is the default twenty, and line width is the default 80. Parses the command line if not already parsed.

Returns:

Help as a string.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

Since:

ostermillerutils 1.07.00

printHelp

public void printHelp()

Print help for the command line options to standard output. Help will be in this format:

 program description
   --argument -a   argument a description
   --another -b       argument b description
   --third -c      argument c description
 

Indentation is the default twenty, and line width is the default eighty. Parses the command line if not already parsed.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

Since:

ostermillerutils 1.07.00

printHelp

public void printHelp(OutputStream out)

Print help for the command line options. Indentation is the default twenty, and line width is the default eighty. Parses the command line if not already parsed.

Parameters:

out - destination to which the help is written.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

Since:

ostermillerutils 1.07.00

printHelp

public void printHelp(Writer out)

Print help for the command line options. Help will be in this format:

 program description
   --argument -a   argument a description
   --another -b       argument b description
   --third -c      argument c description
 

Indentation is the default twenty, and line width is the default eighty. Parses the command line if not already parsed.

Parameters:

out - destination to which the help is written.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

Since:

ostermillerutils 1.07.00

printHelp

public void printHelp(PrintWriter out)

Print help for the command line options. Help will be in this format:

 program description
   --argument -a   argument a description
   --another -b       argument b description
   --third -c      argument c description
 

Indentation is the default twenty, and line width is the default eighty. Parses the command line if not already parsed.

Parameters:

out - destination to which the help is written.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

Since:

ostermillerutils 1.07.00

getHelp

public String getHelp(int indent,
                      int width)

Print help for the command line options. Help will be in this format:

 program description
   --argument -a   argument a description
   --another -b       argument b description
   --third -c      argument c description
 

Parses the command line if not already parsed.

Parameters:

indent - the maximum number of characters to which all descriptions should be indented.

width - the number of characters at which text should be wrapped.

Returns:

Help as a string.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

Since:

ostermillerutils 1.07.00

printHelp

public void printHelp(int indent,
                      int width)

Print help for the command line options to standard output. Help will be in this format:

 program description
   --argument -a   argument a description
   --another -b       argument b description
   --third -c      argument c description
 

Parses the command line if not already parsed.

Parameters:

indent - the maximum number of characters to which all descriptions should be indented.

width - the number of characters at which text should be wrapped.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

Since:

ostermillerutils 1.07.00

printHelp

public void printHelp(OutputStream out,
                      int indent,
                      int width)

Print help for the command line options. Help will be in this format:

 program description
   --argument -a   argument a description
   --another -b       argument b description
   --third -c      argument c description
 

Parses the command line if not already parsed.

Parameters:

out - destination to which the help is written.

indent - the maximum number of characters to which all descriptions should be indented.

width - the number of characters at which text should be wrapped.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

Since:

ostermillerutils 1.07.00

printHelp

public void printHelp(Writer out,
                      int indent,
                      int width)

Print help for the command line options. Help will be in this format:

 program description
   --argument -a   argument a description
   --another -b       argument b description
   --third -c      argument c description
 

Parses the command line if not already parsed.

Parameters:

out - destination to which the help is written.

indent - the maximum number of characters to which all descriptions should be indented.

width - the number of characters at which text should be wrapped.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

Since:

ostermillerutils 1.07.00

printHelp

public void printHelp(PrintWriter out,
                      int indent,
                      int width)

Print help for the command line options. Help will be in this format:

 program description
   --argument -a   argument a description
   --another -b       argument b description
   --third -c      argument c description
 

Parses the command line if not already parsed.

Parameters:

out - destination to which the help is written.

indent - the maximum number of characters to which all descriptions should be indented.

width - the number of characters at which text should be wrapped.

Throws:

UnknownCmdLnOptionException - if an unexpected option is encountered during parsing.

MissingCmdLnArgumentException - if a command line option does not have enough arguments during parsing.

Since:

ostermillerutils 1.07.00