Package org.apache.commons.cli

Class DefaultParser

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  DefaultParser.Builder
      A nested builder class to create DefaultParser instances using descriptive methods.
      static class  DefaultParser.NonOptionAction
      Enum representing possible actions that may be done when "non option" is discovered during parsing.

    • Constructor Summary

      Constructors 
      Modifier 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.
      private DefaultParser​(boolean allowPartialMatching, java.lang.Boolean stripLeadingAndTrailingQuotes, java.util.function.Consumer<Option> deprecatedHandler)
      Creates a new DefaultParser instance with the specified partial matching and quote stripping policy.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void addArg​(java.lang.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.
      private void checkRequiredArgs()
      Throws a MissingArgumentException if the current option didn't receive the number of arguments expected.
      protected void checkRequiredOptions()
      Throws a MissingOptionException if all of the required options are not present.
      private java.lang.String getLongPrefix​(java.lang.String token)
      Searches for a prefix that is the long name of an option (-Xmx512m).
      private java.util.List<java.lang.String> getMatchingLongOptions​(java.lang.String token)
      Gets a list of matching option strings for the given token, depending on the selected partial matching policy.
      protected void handleConcatenatedOptions​(java.lang.String token)
      Breaks token into its constituent parts using the following algorithm.
      private void handleLongOption​(java.lang.String token)
      Handles the following tokens:
      private void handleLongOptionWithEqual​(java.lang.String token)
      Handles the following tokens:
      private void handleLongOptionWithoutEqual​(java.lang.String token)
      Handles the following tokens:
      private void handleOption​(Option option)  
      private void handleProperties​(java.util.Properties properties)
      Sets the values of Options using the values in properties.
      private void handleShortAndLongOption​(java.lang.String hyphenToken)
      Handles the following tokens:
      private void handleToken​(java.lang.String token)
      Handles any command line token.
      protected void handleUnknownToken​(java.lang.String token)
      Handles an unknown token.
      (package private) static int indexOfEqual​(java.lang.String token)  
      private boolean isArgument​(java.lang.String token)
      Tests if the token is a valid argument.
      private boolean isJavaProperty​(java.lang.String token)
      Tests if the specified token is a Java-like property (-Dkey=value).
      private boolean isLongOption​(java.lang.String token)
      Tests if the token looks like a long option.
      private boolean isNegativeNumber​(java.lang.String token)
      Tests if the token is a negative number.
      private boolean isOption​(java.lang.String token)
      Tests if the token looks like an option.
      private boolean isShortOption​(java.lang.String token)
      Tests if the token looks like a short option.
      CommandLine parse​(Options options, java.lang.String[] arguments)
      Parses the arguments according to the specified options.
      CommandLine parse​(Options options, java.lang.String[] arguments, boolean stopAtNonOption)
      Parses the arguments according to the specified options.
      CommandLine parse​(Options options, java.lang.String[] arguments, java.util.Properties properties)
      Parses the arguments according to the specified options and properties.
      CommandLine parse​(Options options, java.lang.String[] arguments, java.util.Properties properties, boolean stopAtNonOption)
      Parses the arguments according to the specified options and properties.
      CommandLine parse​(Options options, java.util.Properties properties, DefaultParser.NonOptionAction nonOptionAction, java.lang.String... arguments)
      Parses the arguments according to the specified options and properties.
      private java.lang.String stripLeadingAndTrailingQuotesDefaultOff​(java.lang.String token)
      Strips balanced leading and trailing quotes if the stripLeadingAndTrailingQuotes is set If stripLeadingAndTrailingQuotes is null, then do not strip
      private java.lang.String stripLeadingAndTrailingQuotesDefaultOn​(java.lang.String token)
      Strips balanced leading and trailing quotes if the stripLeadingAndTrailingQuotes is set If stripLeadingAndTrailingQuotes is null, then do not strip
      private void updateRequiredOptions​(Option option)
      Removes the option or its group from the list of expected elements.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

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

      • currentToken

        protected java.lang.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 java.util.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 java.lang.Boolean stripLeadingAndTrailingQuotes
        Flag indicating if balanced leading and trailing double quotes should be stripped from option arguments. null represents the historic arbitrary behavior

      • deprecatedHandler

        private final java.util.function.Consumer<Option> deprecatedHandler
        The deprecated option handler.

        If you want to serialize this field, use a serialization proxy.

    • Constructor Detail

      • DefaultParser

        public DefaultParser()
        Creates a new DefaultParser instance with partial matching enabled.

        By "partial matching" we mean that given the following 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: 

        
     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,
                      java.lang.Boolean stripLeadingAndTrailingQuotes,
                      java.util.function.Consumer<Option> deprecatedHandler)
        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 Detail

      • indexOfEqual

        static int indexOfEqual​(java.lang.String token)

      • addArg

        protected void addArg​(java.lang.String token)
        Adds token to command line CommandLine.addArg(String).
        Parameters:
        token - the unrecognized option/argument.
        Since:
        1.10.0

      • getLongPrefix

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

      • getMatchingLongOptions

        private java.util.List<java.lang.String> getMatchingLongOptions​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String token)
                                   throws ParseException
        Handles the following tokens: 
         --L -L --l -l
        Parameters:
        token - the command line token to handle.
        Throws:
        ParseException

      • handleProperties

        private void handleProperties​(java.util.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​(java.lang.String hyphenToken)
                               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:
        hyphenToken - the command line token to handle.
        Throws:
        ParseException

      • handleToken

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

      • handleUnknownToken

        protected void handleUnknownToken​(java.lang.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

      • isArgument

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

      • isJavaProperty

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

      • isLongOption

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

      • isNegativeNumber

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

      • isOption

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

      • isShortOption

        private boolean isShortOption​(java.lang.String token)
        Tests if the token looks like a short option.
        Parameters:
        token -

      • parse

        public CommandLine parse​(Options options,
                         java.util.Properties properties,
                         DefaultParser.NonOptionAction nonOptionAction,
                         java.lang.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,
                         java.lang.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,
                         java.lang.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.
        See Also:
        parse(Options, Properties, NonOptionAction, String[])

      • parse

        public CommandLine parse​(Options options,
                         java.lang.String[] arguments,
                         java.util.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,
                         java.lang.String[] arguments,
                         java.util.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.
        See Also:
        parse(Options, Properties, NonOptionAction, String[])

      • stripLeadingAndTrailingQuotesDefaultOff

        private java.lang.String stripLeadingAndTrailingQuotesDefaultOff​(java.lang.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 java.lang.String stripLeadingAndTrailingQuotesDefaultOn​(java.lang.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).