Package org.apache.commons.cli

# Class CommandLine

java.lang.Object
org.apache.commons.cli.CommandLine

All Implemented Interfaces:
  `Serializable`

public class CommandLine extends Object implements Serializable
Represents list of arguments parsed against a `Options` descriptor.

It allows querying of a boolean `hasOption(String opt)`, in addition to retrieving the `getOptionValue(String opt)` for options requiring arguments.

Additionally, any left-over or unrecognized arguments, are available for further processing.

See Also:
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `CommandLine.Builder`
  A nested builder class to create `CommandLine` instance using descriptive methods.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `CommandLine()`
  Creates a command line.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `addArg(String arg)`
  Adds left-over unrecognized option/argument.
  `protected void`
  `addOption(Option opt)`
  Adds an option to the command line.
  `static CommandLine.Builder`
  `builder()`
  Creates a new builder.
  `List<String>`
  `getArgList()`
  Gets any left-over non-recognized options and arguments
  `String[]`
  `getArgs()`
  Gets any left-over non-recognized options and arguments
  `Object`
  `getOptionObject(char opt)`
  Deprecated.
  due to System.err message.
  `Object`
  `getOptionObject(String opt)`
  Deprecated.
  due to System.err message.
  `Properties`
  `getOptionProperties(String opt)`
  Gets the map of values associated to the option.
  `Properties`
  `getOptionProperties(Option option)`
  Gets the map of values associated to the option.
  `Option[]`
  `getOptions()`
  Gets an array of the processed `Option`s.
  `String`
  `getOptionValue(char opt)`
  Gets the first argument, if any, of this option.
  `String`
  `getOptionValue(char opt, String defaultValue)`
  Gets the argument, if any, of an option.
  `String`
  `getOptionValue(char opt, Supplier<String> defaultValue)`
  Gets the argument, if any, of an option.
  `String`
  `getOptionValue(String opt)`
  Gets the first argument, if any, of this option.
  `String`
  `getOptionValue(String opt, String defaultValue)`
  Gets the first argument, if any, of an option.
  `String`
  `getOptionValue(String opt, Supplier<String> defaultValue)`
  Gets the first argument, if any, of an option.
  `String`
  `getOptionValue(Option option)`
  Gets the first argument, if any, of this option.
  `String`
  `getOptionValue(OptionGroup optionGroup)`
  Gets the first argument, if any, of this option group.
  `String`
  `getOptionValue(OptionGroup optionGroup, String defaultValue)`
  Gets the first argument, if any, of an option group.
  `String`
  `getOptionValue(OptionGroup optionGroup, Supplier<String> defaultValue)`
  Gets the first argument, if any, of an option group.
  `String`
  `getOptionValue(Option option, String defaultValue)`
  Gets the first argument, if any, of an option.
  `String`
  `getOptionValue(Option option, Supplier<String> defaultValue)`
  Gets the first argument, if any, of an option.
  `String[]`
  `getOptionValues(char opt)`
  Gets the array of values, if any, of an option.
  `String[]`
  `getOptionValues(String opt)`
  Gets the array of values, if any, of an option.
  `String[]`
  `getOptionValues(Option option)`
  Gets the array of values, if any, of an option.
  `String[]`
  `getOptionValues(OptionGroup optionGroup)`
  Gets the array of values, if any, of an option group.
  `<T> T`
  `getParsedOptionValue(char opt)`
  Gets a version of this `Option` converted to a particular type.
  `<T> T`
  `getParsedOptionValue(char opt, Supplier<T> defaultValue)`
  Gets a version of this `Option` converted to a particular type.
  `<T> T`
  `getParsedOptionValue(char opt, T defaultValue)`
  Gets a version of this `Option` converted to a particular type.
  `<T> T`
  `getParsedOptionValue(String opt)`
  Gets a version of this `Option` converted to a particular type.
  `<T> T`
  `getParsedOptionValue(String opt, Supplier<T> defaultValue)`
  Gets a version of this `Option` converted to a particular type.
  `<T> T`
  `getParsedOptionValue(String opt, T defaultValue)`
  Gets a version of this `Option` converted to a particular type.
  `<T> T`
  `getParsedOptionValue(Option option)`
  Gets a version of this `Option` converted to a particular type.
  `<T> T`
  `getParsedOptionValue(OptionGroup optionGroup)`
  Gets a version of this `OptionGroup` converted to a particular type.
  `<T> T`
  `getParsedOptionValue(OptionGroup optionGroup, Supplier<T> defaultValue)`
  Gets a version of this `OptionGroup` converted to a particular type.
  `<T> T`
  `getParsedOptionValue(OptionGroup optionGroup, T defaultValue)`
  Gets a version of this `OptionGroup` converted to a particular type.
  `<T> T`
  `getParsedOptionValue(Option option, Supplier<T> defaultValue)`
  Gets a version of this `Option` converted to a particular type.
  `<T> T`
  `getParsedOptionValue(Option option, T defaultValue)`
  Gets a version of this `Option` converted to a particular type.
  `boolean`
  `hasOption(char opt)`
  Tests to see if an option has been set.
  `boolean`
  `hasOption(String opt)`
  Tests to see if an option has been set.
  `boolean`
  `hasOption(Option opt)`
  Tests to see if an option has been set.
  `boolean`
  `hasOption(OptionGroup optionGroup)`
  Tests to see if an option has been set.
  `Iterator<Option>`
  `iterator()`
  Returns an iterator over the Option members of CommandLine.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### CommandLine

    protected CommandLine()
    Creates a command line.

- ## Method Details

  - ### builder

    public static CommandLine.Builder builder()
    Creates a new builder.
    Returns:
      a new builder.
    Since:
      1.7.0

  - ### addArg

    protected void addArg(String arg)
    Adds left-over unrecognized option/argument.
    Parameters:
      `arg` - the unrecognized option/argument.

  - ### addOption

    protected void addOption(Option opt)
    Adds an option to the command line. The values of the option are stored.
    Parameters:
      `opt` - the processed option.

  - ### getArgList

    public List<String> getArgList()
    Gets any left-over non-recognized options and arguments
    Returns:
      remaining items passed in but not parsed as a `List`.

  - ### getArgs

    public String[] getArgs()
    Gets any left-over non-recognized options and arguments
    Returns:
      remaining items passed in but not parsed as an array.

  - ### getOptionObject

    @Deprecated public Object getOptionObject(char opt)
    Deprecated.
    due to System.err message. Instead use getParsedOptionValue(char)
    Gets the `Object` type of this `Option`.
    Parameters:
      `opt` - the name of the option.
    Returns:
      the type of opt.

  - ### getOptionObject

    @Deprecated public Object getOptionObject(String opt)
    Deprecated.
    due to System.err message. Instead use getParsedOptionValue(String)
    Gets the `Object` type of this `Option`.
    Parameters:
      `opt` - the name of the option.
    Returns:
      the type of this `Option`.

  - ### getOptionProperties

    public Properties getOptionProperties(Option option)
    Gets the map of values associated to the option. This is convenient for options specifying Java properties like `-Dparam1=value1 -Dparam2=value2`. All odd numbered values are property keys and even numbered values are property values. If there are an odd number of values the last value is assumed to be a boolean flag and the value is "true".
    Parameters:
      `option` - name of the option.
    Returns:
      The Properties mapped by the option, never `null` even if the option doesn't exists.
    Since:
      1.5.0

  - ### getOptionProperties

    public Properties getOptionProperties(String opt)
    Gets the map of values associated to the option. This is convenient for options specifying Java properties like `-Dparam1=value1 -Dparam2=value2`. The first argument of the option is the key, and the 2nd argument is the value. If the option has only one argument (`-Dfoo`) it is considered as a boolean flag and the value is `"true"`.
    Parameters:
      `opt` - name of the option.
    Returns:
      The Properties mapped by the option, never `null` even if the option doesn't exists.
    Since:
      1.2

  - ### getOptions

    public Option[] getOptions()
    Gets an array of the processed `Option`s.
    Returns:
      an array of the processed `Option`s.

  - ### getOptionValue

    public String getOptionValue(char opt)
    Gets the first argument, if any, of this option.
    Parameters:
      `opt` - the character name of the option.
    Returns:
      Value of the argument if option is set, and has an argument, otherwise null.

  - ### getOptionValue

    public String getOptionValue(char opt, String defaultValue)
    Gets the argument, if any, of an option.
    Parameters:
      `opt` - character name of the option
      `defaultValue` - is the default value to be returned if the option is not specified.
    Returns:
      Value of the argument if option is set, and has an argument, otherwise `defaultValue`.

  - ### getOptionValue

    public String getOptionValue(char opt, Supplier<String> defaultValue)
    Gets the argument, if any, of an option.
    Parameters:
      `opt` - character name of the option
      `defaultValue` - is a supplier for the default value to be returned if the option is not specified.
    Returns:
      Value of the argument if option is set, and has an argument, otherwise `defaultValue`.
    Since:
      1.7.0

  - ### getOptionValue

    public String getOptionValue(Option option)
    Gets the first argument, if any, of this option.
    Parameters:
      `option` - the option.
    Returns:
      Value of the argument if option is set, and has an argument, otherwise null.
    Since:
      1.5.0

  - ### getOptionValue

    public String getOptionValue(Option option, String defaultValue)
    Gets the first argument, if any, of an option.
    Parameters:
      `option` - the option.
      `defaultValue` - is the default value to be returned if the option is not specified.
    Returns:
      Value of the argument if option is set, and has an argument, otherwise `defaultValue`.
    Since:
      1.5.0

  - ### getOptionValue

    public String getOptionValue(Option option, Supplier<String> defaultValue)
    Gets the first argument, if any, of an option.
    Parameters:
      `option` - the option.
      `defaultValue` - is a supplier for the default value to be returned if the option is not specified.
    Returns:
      Value of the argument if option is set, and has an argument, otherwise `defaultValue`.
    Since:
      1.7.0

  - ### getOptionValue

    public String getOptionValue(OptionGroup optionGroup)
    Gets the first argument, if any, of this option group.
    Parameters:
      `optionGroup` - the option group.
    Returns:
      Value of the argument if option group is selected, and has an argument, otherwise null.
    Since:
      1.9.0

  - ### getOptionValue

    public String getOptionValue(OptionGroup optionGroup, String defaultValue)
    Gets the first argument, if any, of an option group.
    Parameters:
      `optionGroup` - the option group.
      `defaultValue` - is the default value to be returned if the option group is not selected.
    Returns:
      Value of the argument if option group is selected, and has an argument, otherwise `defaultValue`.
    Since:
      1.9.0

  - ### getOptionValue

    public String getOptionValue(OptionGroup optionGroup, Supplier<String> defaultValue)
    Gets the first argument, if any, of an option group.
    Parameters:
      `optionGroup` - the option group..
      `defaultValue` - is a supplier for the default value to be returned if the option group is not selected.
    Returns:
      Value of the argument if option group is selected, and has an argument, otherwise `defaultValue`.
    Since:
      1.9.0

  - ### getOptionValue

    public String getOptionValue(String opt)
    Gets the first argument, if any, of this option.
    Parameters:
      `opt` - the name of the option.
    Returns:
      Value of the argument if option is set, and has an argument, otherwise null.

  - ### getOptionValue

    public String getOptionValue(String opt, String defaultValue)
    Gets the first argument, if any, of an option.
    Parameters:
      `opt` - name of the option.
      `defaultValue` - is the default value to be returned if the option is not specified.
    Returns:
      Value of the argument if option is set, and has an argument, otherwise `defaultValue`.

  - ### getOptionValue

    public String getOptionValue(String opt, Supplier<String> defaultValue)
    Gets the first argument, if any, of an option.
    Parameters:
      `opt` - name of the option.
      `defaultValue` - is a supplier for the default value to be returned if the option is not specified.
    Returns:
      Value of the argument if option is set, and has an argument, otherwise `defaultValue`.
    Since:
      1.7.0

  - ### getOptionValues

    public String[] getOptionValues(char opt)
    Gets the array of values, if any, of an option.
    Parameters:
      `opt` - character name of the option.
    Returns:
      Values of the argument if option is set, and has an argument, otherwise null.

  - ### getOptionValues

    public String[] getOptionValues(Option option)
    Gets the array of values, if any, of an option.
    Parameters:
      `option` - the option.
    Returns:
      Values of the argument if option is set, and has an argument, otherwise null.
    Since:
      1.5.0

  - ### getOptionValues

    public String[] getOptionValues(OptionGroup optionGroup)
    Gets the array of values, if any, of an option group.
    Parameters:
      `optionGroup` - the option group.
    Returns:
      Values of the argument if option group is selected, and has an argument, otherwise null.
    Since:
      1.9.0

  - ### getOptionValues

    public String[] getOptionValues(String opt)
    Gets the array of values, if any, of an option.
    Parameters:
      `opt` - string name of the option.
    Returns:
      Values of the argument if option is set, and has an argument, otherwise null.

  - ### getParsedOptionValue

    public <T> T getParsedOptionValue(char opt) throws ParseException
    Gets a version of this `Option` converted to a particular type.
    Type Parameters:
      `T` - The return type for the method.
    Parameters:
      `opt` - the name of the option.
    Returns:
      the value parsed into a particular object.
    Throws:
      `ParseException` - if there are problems turning the option value into the desired type
    Since:
      1.5.0
    See Also:
      - `PatternOptionBuilder`

  - ### getParsedOptionValue

    public <T> T getParsedOptionValue(char opt, Supplier<T> defaultValue) throws ParseException
    Gets a version of this `Option` converted to a particular type.
    Type Parameters:
      `T` - The return type for the method.
    Parameters:
      `opt` - the name of the option.
      `defaultValue` - the default value to return if opt is not set.
    Returns:
      the value parsed into a particular object.
    Throws:
      `ParseException` - if there are problems turning the option value into the desired type
    Since:
      1.7.0
    See Also:
      - `PatternOptionBuilder`

  - ### getParsedOptionValue

    public <T> T getParsedOptionValue(char opt, T defaultValue) throws ParseException
    Gets a version of this `Option` converted to a particular type.
    Type Parameters:
      `T` - The return type for the method.
    Parameters:
      `opt` - the name of the option.
      `defaultValue` - the default value to return if opt is not set.
    Returns:
      the value parsed into a particular object.
    Throws:
      `ParseException` - if there are problems turning the option value into the desired type
    Since:
      1.7.0
    See Also:
      - `PatternOptionBuilder`

  - ### getParsedOptionValue

    public <T> T getParsedOptionValue(Option option) throws ParseException
    Gets a version of this `Option` converted to a particular type.
    Type Parameters:
      `T` - The return type for the method.
    Parameters:
      `option` - the option.
    Returns:
      the value parsed into a particular object.
    Throws:
      `ParseException` - if there are problems turning the option value into the desired type
    Since:
      1.5.0
    See Also:
      - `PatternOptionBuilder`

  - ### getParsedOptionValue

    public <T> T getParsedOptionValue(Option option, Supplier<T> defaultValue) throws ParseException
    Gets a version of this `Option` converted to a particular type.
    Type Parameters:
      `T` - The return type for the method.
    Parameters:
      `option` - the option.
      `defaultValue` - the default value to return if opt is not set.
    Returns:
      the value parsed into a particular object.
    Throws:
      `ParseException` - if there are problems turning the option value into the desired type
    Since:
      1.7.0
    See Also:
      - `PatternOptionBuilder`

  - ### getParsedOptionValue

    public <T> T getParsedOptionValue(Option option, T defaultValue) throws ParseException
    Gets a version of this `Option` converted to a particular type.
    Type Parameters:
      `T` - The return type for the method.
    Parameters:
      `option` - the option.
      `defaultValue` - the default value to return if opt is not set.
    Returns:
      the value parsed into a particular object.
    Throws:
      `ParseException` - if there are problems turning the option value into the desired type
    Since:
      1.7.0
    See Also:
      - `PatternOptionBuilder`

  - ### getParsedOptionValue

    public <T> T getParsedOptionValue(OptionGroup optionGroup) throws ParseException
    Gets a version of this `OptionGroup` converted to a particular type.
    Type Parameters:
      `T` - The return type for the method.
    Parameters:
      `optionGroup` - the option group.
    Returns:
      the value parsed into a particular object.
    Throws:
      `ParseException` - if there are problems turning the selected option value into the desired type
    Since:
      1.9.0
    See Also:
      - `PatternOptionBuilder`

  - ### getParsedOptionValue

    public <T> T getParsedOptionValue(OptionGroup optionGroup, Supplier<T> defaultValue) throws ParseException
    Gets a version of this `OptionGroup` converted to a particular type.
    Type Parameters:
      `T` - The return type for the method.
    Parameters:
      `optionGroup` - the option group.
      `defaultValue` - the default value to return if opt is not set.
    Returns:
      the value parsed into a particular object.
    Throws:
      `ParseException` - if there are problems turning the selected option value into the desired type
    Since:
      1.9.0
    See Also:
      - `PatternOptionBuilder`

  - ### getParsedOptionValue

    public <T> T getParsedOptionValue(OptionGroup optionGroup, T defaultValue) throws ParseException
    Gets a version of this `OptionGroup` converted to a particular type.
    Type Parameters:
      `T` - The return type for the method.
    Parameters:
      `optionGroup` - the option group.
      `defaultValue` - the default value to return if an option is not selected.
    Returns:
      the value parsed into a particular object.
    Throws:
      `ParseException` - if there are problems turning the option value into the desired type
    Since:
      1.9.0
    See Also:
      - `PatternOptionBuilder`

  - ### getParsedOptionValue

    public <T> T getParsedOptionValue(String opt) throws ParseException
    Gets a version of this `Option` converted to a particular type.
    Type Parameters:
      `T` - The return type for the method.
    Parameters:
      `opt` - the name of the option.
    Returns:
      the value parsed into a particular object.
    Throws:
      `ParseException` - if there are problems turning the option value into the desired type
    Since:
      1.2
    See Also:
      - `PatternOptionBuilder`

  - ### getParsedOptionValue

    public <T> T getParsedOptionValue(String opt, Supplier<T> defaultValue) throws ParseException
    Gets a version of this `Option` converted to a particular type.
    Type Parameters:
      `T` - The return type for the method.
    Parameters:
      `opt` - the name of the option.
      `defaultValue` - the default value to return if opt is not set.
    Returns:
      the value parsed into a particular object.
    Throws:
      `ParseException` - if there are problems turning the option value into the desired type
    Since:
      1.7.0
    See Also:
      - `PatternOptionBuilder`

  - ### getParsedOptionValue

    public <T> T getParsedOptionValue(String opt, T defaultValue) throws ParseException
    Gets a version of this `Option` converted to a particular type.
    Type Parameters:
      `T` - The return type for the method.
    Parameters:
      `opt` - the name of the option.
      `defaultValue` - the default value to return if opt is not set.
    Returns:
      the value parsed into a particular object.
    Throws:
      `ParseException` - if there are problems turning the option value into the desired type
    Since:
      1.7.0
    See Also:
      - `PatternOptionBuilder`

  - ### hasOption

    public boolean hasOption(char opt)
    Tests to see if an option has been set.
    Parameters:
      `opt` - character name of the option.
    Returns:
      true if set, false if not.

  - ### hasOption

    public boolean hasOption(Option opt)
    Tests to see if an option has been set.
    Parameters:
      `opt` - the option to check.
    Returns:
      true if set, false if not.
    Since:
      1.5.0

  - ### hasOption

    public boolean hasOption(OptionGroup optionGroup)
    Tests to see if an option has been set.
    Parameters:
      `optionGroup` - the option group to check.
    Returns:
      true if set, false if not.
    Since:
      1.9.0

  - ### hasOption

    public boolean hasOption(String opt)
    Tests to see if an option has been set.
    Parameters:
      `opt` - Short name of the option.
    Returns:
      true if set, false if not.

  - ### iterator

    public Iterator<Option> iterator()
    Returns an iterator over the Option members of CommandLine.
    Returns:
      an `Iterator` over the processed `Option` members of this `CommandLine`.