Java Doc for OptionParser.java in  » Development » JOpt-Simple » joptsimple » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Parses command line arguments according to GNU's conventions.

This parser supports both short options and long options.

• Short options begin with a single hyphen ("-") followed by a single letter or digit.
• Short options can accept single arguments. The argument can be made required or optional. The option can occur in:
  • the argument after the option, as in -d /tmp
  • right up against it, as in -d/tmp
  • right up against it separated by an equals sign ("="), as in -d=/tmp
• Short options can be clustered, so that -abc is treated as -a -b -c, if none of those options can accept arguments.
• An argument consisting only of two hyphens ("--") signals that the remaining arguments are to be treated as non-options.
• An argument consisting only of a single hyphen is considered a non-option argument (though it can be an argument of an option). Many Unix programs treat single hyphens as stand-ins for the standard input or standard output streams.
• Long options generally begin with two hyphens ("--"), followed by multiple letters and/or digits.
• You can abbreviate long options, so long as the abbreviation is unique.
• Long options can accept single arguments. The argument can be made required or optional. The option can occur in:
  • the argument after the option, as in --directory /tmp
  • right up against it separated by an equals sign ("="), as in --directory=/tmp
• You can use a single hyphen ("-") instead of a double hyphen ("--") for a long option.
• The option -W is reserved. If you tell the parser to , then it will treat, for example, -W foo=bar as the long option foo with argument bar, as though you had written --foo=bar.
• You can specify -W as a valid short option, or use it as an abbreviation for a long option, but will always supersede this behavior.
• You can specify a given short or long option multiple times on a single command line. The parser collects any arguments specified for those options as a list.
• If the parser detects an option whose argument is optional, and the next argument "looks like" an option, that argument is not treated as the argument to the option, but as a potentially valid option. If, on the other hand, the optional argument is typed as a derivative of Number , then that argument is treated as the negative number argument of the option, even if the parser recognizes the corresponding numeric option. For example:

   parser.accepts( "a" ).withOptionalArg().ofType( Integer.class );
   parser.accepts( "1" );
   OptionSet options = parser.parse( new String[] { "-a", "-1" } );
   

  In this case, the option set contains "a" with argument -1, not both "a" and "1". Swapping the elements in the args array gives the latter.

There are two ways to tell the parser what options to recognize:

1. A "domain-specific language"-style API for specifying options, available since version 2. Sentences in this domain-specific language begin with a call to OptionParser.accepts(String) accepts ; methods on the ensuing chain of objects describe whether the option passed to OptionParser.accepts(String) accepts can take an argument, whether the argument is required or optional, and to what type arguments of the option should be converted.
2. Since version 1, a more concise way of specifying short options to recognize has been to use the special . Arguments of options specified in this manner will be of type String . Here are the rules for the format of the specification strings this constructor accepts:
   • Any letter or digit is treated as an option character.
   • If an option character is followed by a single colon (":"), then the option requires an argument.
   • If an option character is followed by two colons ("::"), then the option accepts an optional argument.
   • Otherwise, the option character accepts no argument.
   • If the option specification string begins with a plus sign ("+"), the parser will behave "POSIX-ly correct".
   • If the option specification string contains the sequence "W;" (capital W followed by a semicolon), the parser will recognize the alternative form of long options.

By default, as with GNU getopt(), the parser allows intermixing of options and non-options. If, however, the parser has been created to be "POSIX-ly correct", then the first argument that does not look lexically like an option, and is not a required argument of a preceding option, signals the end of options. You can still bind optional arguments to their options using the abutting (for short options) or = syntax.

Unlike GNU getopt(), this parser does not honor the environment variable POSIXLY_CORRECT. "POSIX-ly correct" parsers are configured by either:

1. using the method OptionParser.setPosixlyCorrect(boolean) , or
2. using the with an argument whose first character is a plus sign ("+")

Arguments of options specified this way will be of type String .
since:
   1.0
Parameters:
  optionSpecification - an option specification
throws:
  NullPointerException - if optionSpecification isnull

This method returns an instance of OptionSpecBuilder to allow the formation of parser directives as sentences in a domain-specific language. For example:

 OptionParser parser = new OptionParser();
 parser.accepts( "c" ).withRequiredArg().ofType( Integer.class );