com.Ostermiller.util Java Utilities


com.Ostermiller.util
Class CmdLn

java.lang.Object
  extended by 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
Author:
Stephen Ostermiller http://ostermiller.org/contact.pl?regarding=Java+Utilities

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
equals, 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

com.Ostermiller.util Java Utilities


Copyright © 2001-2012 by Stephen Ostermiller