Class CmdLn

Method Details

• 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