Package org.apache.commons.cli

# Class DefaultParser

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

All Implemented Interfaces:
  `CommandLineParser`

public class DefaultParser extends Object implements CommandLineParser
Default parser.

Since:
  1.3

- ## Nested Class Summary

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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected CommandLine`
  `cmd`
  The command-line instance.
  `protected Option`
  `currentOption`
  The last option parsed.
  `protected String`
  `currentToken`
  The token currently processed.
  `protected List`
  `expectedOpts`
  The required options and groups expected to be found when parsing the command line.
  `protected Options`
  `options`
  The current options.
  `protected boolean`
  `skipParsing`
  Flag indicating if tokens should no longer be analyzed and simply added as arguments of the command line.
  `protected boolean`
  `stopAtNonOption`
  Flag indicating how unrecognized tokens are handled.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DefaultParser()`
  Creates a new DefaultParser instance with partial matching enabled.
  `DefaultParser(boolean allowPartialMatching)`
  Create a new DefaultParser instance with the specified partial matching policy.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static DefaultParser.Builder`
  `builder()`
  Creates a new `DefaultParser.Builder` to create an `DefaultParser` using descriptive methods.
  `protected void`
  `checkRequiredOptions()`
  Throws a `MissingOptionException` if all of the required options are not present.
  `protected void`
  `handleConcatenatedOptions(String token)`
  Breaks `token` into its constituent parts using the following algorithm.
  `CommandLine`
  `parse(Options options, String[] arguments)`
  Parses the arguments according to the specified options.
  `CommandLine`
  `parse(Options options, String[] arguments, boolean stopAtNonOption)`
  Parses the arguments according to the specified options.
  `CommandLine`
  `parse(Options options, String[] arguments, Properties properties)`
  Parses the arguments according to the specified options and properties.
  `CommandLine`
  `parse(Options options, String[] arguments, Properties properties, boolean stopAtNonOption)`
  Parses the arguments according to the specified options and properties.

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

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

- ## Field Details

  - ### cmd

    protected CommandLine cmd
    The command-line instance.

  - ### options

    protected Options options
    The current options.

  - ### stopAtNonOption

    protected boolean stopAtNonOption
    Flag indicating how unrecognized tokens are handled. `true` to stop the parsing and add the remaining tokens to the args list. `false` to throw an exception.

  - ### currentToken

    protected String currentToken
    The token currently processed.

  - ### currentOption

    protected Option currentOption
    The last option parsed.

  - ### skipParsing

    protected boolean skipParsing
    Flag indicating if tokens should no longer be analyzed and simply added as arguments of the command line.

  - ### expectedOpts

    protected List expectedOpts
    The required options and groups expected to be found when parsing the command line.

- ## Constructor Details

  - ### DefaultParser

    public DefaultParser()
    Creates a new DefaultParser instance with partial matching enabled. By "partial matching" we mean that given the following code:

         {
             @code
             final Options options = new Options();
             options.addOption(new Option("d", "debug", false, "Turn on debug."));
             options.addOption(new Option("e", "extract", false, "Turn on extract."));
             options.addOption(new Option("o", "option", true, "Turn on option with argument."));
         }

    with "partial matching" turned on, `-de` only matches the `"debug"` option. However, with "partial matching" disabled, `-de` would enable both `debug` as well as `extract` options.

  - ### DefaultParser

    public DefaultParser(boolean allowPartialMatching)
    Create a new DefaultParser instance with the specified partial matching policy. By "partial matching" we mean that given the following code:

         {
             @code
             final Options options = new Options();
             options.addOption(new Option("d", "debug", false, "Turn on debug."));
             options.addOption(new Option("e", "extract", false, "Turn on extract."));
             options.addOption(new Option("o", "option", true, "Turn on option with argument."));
         }

    with "partial matching" turned on, `-de` only matches the `"debug"` option. However, with "partial matching" disabled, `-de` would enable both `debug` as well as `extract` options.
    Parameters:
      `allowPartialMatching` - if partial matching of long options shall be enabled

- ## Method Details

  - ### builder

    public static DefaultParser.Builder builder()
    Creates a new `DefaultParser.Builder` to create an `DefaultParser` using descriptive methods.
    Returns:
      a new `DefaultParser.Builder` instance
    Since:
      1.5.0

  - ### checkRequiredOptions

    protected void checkRequiredOptions() throws MissingOptionException
    Throws a `MissingOptionException` if all of the required options are not present.
    Throws:
      `MissingOptionException` - if any of the required Options are not present.

  - ### handleConcatenatedOptions

    protected void handleConcatenatedOptions(String token) throws ParseException
    Breaks `token` into its constituent parts using the following algorithm.
    - ignore the first character ("-")
    - for each remaining character check if an `Option` exists with that id.
    - if an `Option` does exist then add that character prepended with "-" to the list of processed tokens.
    - if the `Option` can have an argument value and there are remaining characters in the token then add the remaining characters as a token to the list of processed tokens.
    - if an `Option` does NOT exist AND `stopAtNonOption` IS set then add the special token "--" followed by the remaining characters and also the remaining tokens directly to the processed tokens list.
    - if an `Option` does NOT exist AND `stopAtNonOption` IS NOT set then add that character prepended with "-".
    Parameters:
      `token` - The current token to be burst at the first non-Option encountered.
    Throws:
      `ParseException` - if there are any problems encountered while parsing the command line token.

  - ### parse

    public CommandLine parse(Options options, String[] arguments) throws ParseException
    Description copied from interface: `CommandLineParser`
    Parses the arguments according to the specified options.
    Specified by:
      `parse` in interface `CommandLineParser`
    Parameters:
      `options` - the specified Options
      `arguments` - the command line arguments
    Returns:
      the list of atomic option and value tokens
    Throws:
      `ParseException` - if there are any problems encountered while parsing the command line tokens.

  - ### parse

    public CommandLine parse(Options options, String[] arguments, boolean stopAtNonOption) throws ParseException
    Description copied from interface: `CommandLineParser`
    Parses the arguments according to the specified options.
    Specified by:
      `parse` in interface `CommandLineParser`
    Parameters:
      `options` - the specified Options
      `arguments` - the command line arguments
      `stopAtNonOption` - if `true` an unrecognized argument stops the parsing and the remaining arguments are added to the `CommandLine`s args list. If `false` an unrecognized argument triggers a ParseException.
    Returns:
      the list of atomic option and value tokens
    Throws:
      `ParseException` - if there are any problems encountered while parsing the command line tokens.

  - ### parse

    public CommandLine parse(Options options, String[] arguments, Properties properties) throws ParseException
    Parses the arguments according to the specified options and properties.
    Parameters:
      `options` - the specified Options
      `arguments` - the command line arguments
      `properties` - command line option name-value pairs
    Returns:
      the list of atomic option and value tokens
    Throws:
      `ParseException` - if there are any problems encountered while parsing the command line tokens.

  - ### parse

    public CommandLine parse(Options options, String[] arguments, Properties properties, boolean stopAtNonOption) throws ParseException
    Parses the arguments according to the specified options and properties.
    Parameters:
      `options` - the specified Options
      `arguments` - the command line arguments
      `properties` - command line option name-value pairs
      `stopAtNonOption` - if `true` an unrecognized argument stops the parsing and the remaining arguments are added to the `CommandLine`s args list. If `false` an unrecognized argument triggers a ParseException.
    Returns:
      the list of atomic option and value tokens
    Throws:
      `ParseException` - if there are any problems encountered while parsing the command line tokens.