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

  • 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.

    • allowPartialMatching

      private final boolean allowPartialMatching
      Flag indicating if partial matching of long options is supported.

    • stripLeadingAndTrailingQuotes

      private final Boolean stripLeadingAndTrailingQuotes
      Flag indicating if balanced leading and trailing double quotes should be stripped from option arguments. null represents the historic arbitrary behaviour

  • 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

    • DefaultParser

      private DefaultParser(boolean allowPartialMatching, Boolean stripLeadingAndTrailingQuotes)
      Creates a new DefaultParser instance with the specified partial matching and quote stripping policy.
      Parameters:
      allowPartialMatching - if partial matching of long options shall be enabled
      stripLeadingAndTrailingQuotes - if balanced outer double quoutes should be stripped

  • 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

    • checkRequiredArgs

      private void checkRequiredArgs() throws ParseException
      Throws a MissingArgumentException if the current option didn't receive the number of arguments expected.
      Throws:
      ParseException

    • 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.

    • getLongPrefix

      private String getLongPrefix(String token)
      Searches for a prefix that is the long name of an option (-Xmx512m)
      Parameters:
      token -

    • getMatchingLongOptions

      private List<String> getMatchingLongOptions(String token)
      Gets a list of matching option strings for the given token, depending on the selected partial matching policy.
      Parameters:
      token - the token (may contain leading dashes)
      Returns:
      the list of matching option strings or an empty list if no matching option could be found

    • 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.

    • handleLongOption

      private void handleLongOption(String token) throws ParseException
      Handles the following tokens: --L --L=V --L V --l
      Parameters:
      token - the command line token to handle
      Throws:
      ParseException

    • handleLongOptionWithEqual

      private void handleLongOptionWithEqual(String token) throws ParseException
      Handles the following tokens: --L=V -L=V --l=V -l=V
      Parameters:
      token - the command line token to handle
      Throws:
      ParseException

    • handleLongOptionWithoutEqual

      private void handleLongOptionWithoutEqual(String token) throws ParseException
      Handles the following tokens: --L -L --l -l
      Parameters:
      token - the command line token to handle
      Throws:
      ParseException

    • handleOption

      private void handleOption(Option option) throws ParseException
      Throws:
      ParseException

    • handleProperties

      private void handleProperties(Properties properties) throws ParseException
      Sets the values of Options using the values in properties.
      Parameters:
      properties - The value properties to be processed.
      Throws:
      ParseException

    • handleShortAndLongOption

      private void handleShortAndLongOption(String token) throws ParseException
      Handles the following tokens: -S -SV -S V -S=V -S1S2 -S1S2 V -SV1=V2 -L -LV -L V -L=V -l
      Parameters:
      token - the command line token to handle
      Throws:
      ParseException

    • handleToken

      private void handleToken(String token) throws ParseException
      Handles any command line token.
      Parameters:
      token - the command line token to handle
      Throws:
      ParseException

    • handleUnknownToken

      private 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

    • isArgument

      private boolean isArgument(String token)
      Tests if the token is a valid argument.
      Parameters:
      token -

    • isJavaProperty

      private boolean isJavaProperty(String token)
      Tests if the specified token is a Java-like property (-Dkey=value).

    • isLongOption

      private boolean isLongOption(String token)
      Tests if the token looks like a long option.
      Parameters:
      token -

    • isNegativeNumber

      private boolean isNegativeNumber(String token)
      Tests if the token is a negative number.
      Parameters:
      token -

    • isOption

      private boolean isOption(String token)
      Tests if the token looks like an option.
      Parameters:
      token -

    • isShortOption

      private boolean isShortOption(String token)
      Tests if the token looks like a short option.
      Parameters:
      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 CommandLines 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 CommandLines 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.

    • stripLeadingAndTrailingQuotesDefaultOff

      private String stripLeadingAndTrailingQuotesDefaultOff(String token)
      Strips balanced leading and trailing quotes if the stripLeadingAndTrailingQuotes is set If stripLeadingAndTrailingQuotes is null, then do not strip
      Parameters:
      token - a string
      Returns:
      token with the quotes stripped (if set)

    • stripLeadingAndTrailingQuotesDefaultOn

      private String stripLeadingAndTrailingQuotesDefaultOn(String token)
      Strips balanced leading and trailing quotes if the stripLeadingAndTrailingQuotes is set If stripLeadingAndTrailingQuotes is null, then do not strip
      Parameters:
      token - a string
      Returns:
      token with the quotes stripped (if set)

    • updateRequiredOptions

      private void updateRequiredOptions(Option option) throws AlreadySelectedException
      Removes the option or its group from the list of expected elements.
      Parameters:
      option -
      Throws:
      AlreadySelectedException