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.
  `static enum`
  `DefaultParser.NonOptionAction`
  Enum representing possible actions that may be done when "non option" is discovered during parsing.

- ## 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 DefaultParser.NonOptionAction`
  `nonOptionAction`
  Action to happen when "non option" token is discovered.
  `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`
  Deprecated.
  Use `nonOptionAction` instead.

- ## 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
  `protected void`
  `addArg(String token)`
  Adds token to command line `CommandLine.addArg(String)`.
  `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.
  `protected void`
  `handleUnknownToken(String token)`
  Handles an unknown token.
  `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.
  `CommandLine`
  `parse(Options options, Properties properties, DefaultParser.NonOptionAction nonOptionAction, String... arguments)`
  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

    @Deprecated protected boolean stopAtNonOption
    Deprecated.
    Use `nonOptionAction` instead. This field is unused, and left for binary compatibility reasons.
    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.

  - ### nonOptionAction

    protected DefaultParser.NonOptionAction nonOptionAction
    Action to happen when "non option" token is discovered.
    Since:
      1.10.0

  - ### 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

  - ### addArg

    protected void addArg(String token)
    Adds token to command line `CommandLine.addArg(String)`.
    Parameters:
      `token` - the unrecognized option/argument.
    Since:
      1.10.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.

  - ### handleUnknownToken

    protected void handleUnknownToken(String token) throws ParseException
    Handles an unknown token. If the token starts with a dash an UnrecognizedOptionException is thrown. Otherwise the token is added to the arguments of the command line. If the stopAtNonOption flag is set, this stops the parsing and the remaining tokens are added as-is in the arguments of the command line.
    Parameters:
      `token` - the command line token to handle.
    Throws:
      `ParseException` - if parsing should fail.
    Since:
      1.10.0

  - ### parse

    public CommandLine parse(Options options, Properties properties, DefaultParser.NonOptionAction nonOptionAction, String... arguments) throws ParseException
    Parses the arguments according to the specified options and properties.
    Parameters:
      `options` - the specified Options
      `properties` - command line option name-value pairs
      `nonOptionAction` - see `DefaultParser.NonOptionAction`.
      `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.
    Since:
      1.10.0

  - ### 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.
    See Also:
      - `parse(Options, Properties, NonOptionAction, String[])`

  - ### 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.
    See Also:
      - `parse(Options, Properties, NonOptionAction, String[])`