OptionParser (GemFire XD Java API Documentation)

java.lang.Object
- joptsimple.OptionParser

```
public class OptionParser
extends Object
```
Parses command line arguments, using a syntax that attempts to take from the best of POSIX getopt() and GNU getopt_long().

This parser supports short options and long options.
- Short options begin with a single hyphen ("-") followed by a single letter or digit, or question mark ("?"), or dot (".").
- Short options can accept single arguments. The argument can be made required or optional. The option's argument can occur:
  - in the slot after the option, as in -d /tmp
  - right up against the option, as in -d/tmp
  - right up against the option separated by an equals sign ("="), as in -d=/tmp
  To specify n arguments for an option, specify the option n times, once for each argument, as in -d /tmp -d /var -d /opt; or, when using the "separated values" clause of the "fluent interface" (see below), give multiple values separated by a given character as a single argument to the option.
- Short options can be clustered, so that -abc is treated as -a -b -c. If a short option in the cluster can accept an argument, the remaining characters are interpreted as the argument for that option.
- 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 begin with two hyphens ("--"), followed by multiple letters, digits, hyphens, question marks, or dots. A hyphen cannot be the first character of a long option specification when configuring the parser.
- 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's argument can occur:
  - in the slot after the option, as in --directory /tmp
  - right up against the option separated by an equals sign ("="), as in --directory=/tmp
  Specify multiple arguments for a long option in the same manner as for short options (see above).
- 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 recognize alternative long options, 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 recognizing alternative long options 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:
```
     OptionParser parser = new OptionParser();
     parser.accepts( "a" ).withOptionalArg().ofType( Integer.class );
     parser.accepts( "2" );
     OptionSet options = parser.parse( "-a", "-2" );
   
```
  In this case, the option set contains "a" with argument -2, not both "a" and "2". Swapping the elements in the args array gives the latter.
There are two ways to tell the parser what options to recognize:
1. A "fluent interface"-style API for specifying options, available since version 2. Sentences in this fluent interface language begin with a call to accepts or acceptsAll methods; calls on the ensuing chain of objects describe whether the options can take an argument, whether the argument is required or optional, to what type arguments of the options should be converted if any, etc. Since version 3, these calls return an instance of OptionSpec, which can subsequently be used to retrieve the arguments of the associated option in a type-safe manner.
2. Since version 1, a more concise way of specifying short options has been to use the special constructor. 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.
  - An option character can be immediately followed by an asterisk (*) to indicate that the option is a "help" option.
  - If an option character (with possible trailing asterisk) is followed by a single colon (":"), then the option requires an argument.
  - If an option character (with possible trailing asterisk) 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.
Each of the options in a list of options given to acceptsAll is treated as a synonym of the others. For example:
```
     
     OptionParser parser = new OptionParser();
     parser.acceptsAll( asList( "w", "interactive", "confirmation" ) );
     OptionSet options = parser.parse( "-w" );
     
   
```
In this case, options.has would answer true when given arguments "w", "interactive", and "confirmation". The OptionSet would give the same responses to these arguments for its other methods as well.

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 posixlyCorrect(boolean), or
2. using the constructor with an argument whose first character is a plus sign ("+")
See Also:
The GNU C Library

Constructor Summary

Constructors
Constructor and Description
`OptionParser()` Creates an option parser that initially recognizes no options, and does not exhibit "POSIX-ly correct" behavior.
`OptionParser(boolean disableShortOption)` Creates an option parser that initially recognizes no options, and does not exhibit "POSIX-ly correct" behavior.
`OptionParser(String optionSpecification)` Creates an option parser and configures it to recognize the short options specified in the given string.
`OptionParser(String optionSpecification, boolean disableShortOption)` Creates an option parser and configures it to recognize the short options specified in the given string.

Method Summary

Methods
Modifier and Type	Method and Description
`OptionSpecBuilder`	`accepts(String option)` Tells the parser to recognize the given option.
`OptionSpecBuilder`	`accepts(String option, String description)` Tells the parser to recognize the given option.
`OptionSpecBuilder`	`acceptsAll(Collection<String> options)` Tells the parser to recognize the given options, and treat them as synonymous.
`OptionSpecBuilder`	`acceptsAll(Collection<String> options, String description)` Tells the parser to recognize the given options, and treat them as synonymous.
`void`	`formatHelpWith(HelpFormatter formatter)` Tells the parser to use the given formatter when asked to print help.
`boolean`	`isShortOptionDisabled()`
`OptionSet`	`parse(String... arguments)` Parses the given command line arguments according to the option specifications given to the parser.
`void`	`posixlyCorrect(boolean setting)` Tells the parser whether or not to behave "POSIX-ly correct"-ly.
`void`	`printHelpOn(OutputStream sink)` Writes information about the options this parser recognizes to the given output sink.
`void`	`printHelpOn(Writer sink)` Writes information about the options this parser recognizes to the given output sink.
`void`	`recognizeAlternativeLongOptions(boolean recognize)` Tells the parser either to recognize or ignore `"-W"`-style long options.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - OptionParser
```
public OptionParser()
```
    Creates an option parser that initially recognizes no options, and does not exhibit "POSIX-ly correct" behavior.
  - OptionParser
```
public OptionParser(String optionSpecification)
```
    Creates an option parser and configures it to recognize the short options specified in the given string. Arguments of options specified this way will be of type String.
    
    Parameters:
    optionSpecification - an option specification
    
    Throws:
    
    NullPointerException - if optionSpecification is null
    
    OptionException - if the option specification contains illegal characters or otherwise cannot be recognized
  - OptionParser
```
public OptionParser(boolean disableShortOption)
```
    Creates an option parser that initially recognizes no options, and does not exhibit "POSIX-ly correct" behavior. Short options can be enabled with setting disableShortOption to false.
    
    Parameters:
    disableShortOption - true to disable short options, false to enable
  - OptionParser
```
public OptionParser(String optionSpecification,
            boolean disableShortOption)
```
    Creates an option parser and configures it to recognize the short options specified in the given string. Arguments of options specified this way will be of type String. Short options can be enabled with setting disableShortOption to false.
    
    Parameters:
    optionSpecification - an option specification
    disableShortOption - true to disable short options, false to enable those.
    
    Throws:
    
    NullPointerException - if optionSpecification is null
    
    OptionException - if the option specification contains illegal characters or otherwise cannot be recognized
- Method Detail
  - accepts
```
public OptionSpecBuilder accepts(String option)
```
    Tells the parser to recognize the given option.
    
    This method returns an instance of OptionSpecBuilder to allow the formation of parser directives as sentences in a fluent interface language. For example:
```
   OptionParser parser = new OptionParser();
   parser.accepts( "c" ).withRequiredArg().ofType( Integer.class );
 
```
    If no methods are invoked on the returned OptionSpecBuilder, then the parser treats the option as accepting no argument.
    Parameters:
    option - the option to recognize
    
    Returns:
    an object that can be used to flesh out more detail about the option
    
    Throws:
    
    OptionException - if the option contains illegal characters
    
    NullPointerException - if the option is null
  - accepts
```
public OptionSpecBuilder accepts(String option,
                        String description)
```
    Tells the parser to recognize the given option.
    
    Parameters:
    option - the option to recognize
    description - a string that describes the purpose of the option. This is used when generating help information about the parser.
    
    Returns:
    an object that can be used to flesh out more detail about the option
    
    Throws:
    
    OptionException - if the option contains illegal characters
    
    NullPointerException - if the option is null
    See Also:
    accepts(String)
  - acceptsAll
```
public OptionSpecBuilder acceptsAll(Collection<String> options)
```
    Tells the parser to recognize the given options, and treat them as synonymous.
    
    Parameters:
    options - the options to recognize and treat as synonymous
    
    Returns:
    an object that can be used to flesh out more detail about the options
    
    Throws:
    
    OptionException - if any of the options contain illegal characters
    
    NullPointerException - if the option list or any of its elements are null
    See Also:
    accepts(String)
  - acceptsAll
```
public OptionSpecBuilder acceptsAll(Collection<String> options,
                           String description)
```
    Tells the parser to recognize the given options, and treat them as synonymous.
    
    Parameters:
    options - the options to recognize and treat as synonymous
    description - a string that describes the purpose of the option. This is used when generating help information about the parser.
    
    Returns:
    an object that can be used to flesh out more detail about the options
    
    Throws:
    
    OptionException - if any of the options contain illegal characters
    
    NullPointerException - if the option list or any of its elements are null
    
    IllegalArgumentException - if the option list is empty
    See Also:
    acceptsAll(Collection)
  - posixlyCorrect
```
public void posixlyCorrect(boolean setting)
```
    Tells the parser whether or not to behave "POSIX-ly correct"-ly.
    
    Parameters:
    setting - true if the parser should behave "POSIX-ly correct"-ly
  - recognizeAlternativeLongOptions
```
public void recognizeAlternativeLongOptions(boolean recognize)
```
    Tells the parser either to recognize or ignore "-W"-style long options.
    
    Parameters:
    recognize - true if the parser is to recognize the special style of long options
  - printHelpOn
```
public void printHelpOn(OutputStream sink)
                 throws IOException
```
    Writes information about the options this parser recognizes to the given output sink. The output sink is flushed, but not closed.
    
    Parameters:
    sink - the sink to write information to
    
    Throws:
    
    IOException - if there is a problem writing to the sink
    
    NullPointerException - if sink is null
    See Also:
    printHelpOn(Writer)
  - printHelpOn
```
public void printHelpOn(Writer sink)
                 throws IOException
```
    Writes information about the options this parser recognizes to the given output sink. The output sink is flushed, but not closed.
    
    Parameters:
    sink - the sink to write information to
    
    Throws:
    
    IOException - if there is a problem writing to the sink
    
    NullPointerException - if sink is null
    See Also:
    printHelpOn(OutputStream)
  - formatHelpWith
```
public void formatHelpWith(HelpFormatter formatter)
```
    Tells the parser to use the given formatter when asked to print help.
    
    Parameters:
    formatter - the formatter to use for printing help
    
    Throws:
    
    NullPointerException - if the formatter is null
  - parse
```
public OptionSet parse(String... arguments)
```
    Parses the given command line arguments according to the option specifications given to the parser.
    
    Parameters:
    arguments - arguments to parse
    
    Returns:
    an OptionSet describing the parsed options, their arguments, and any non-option arguments found
    
    Throws:
    
    OptionException - if problems are detected while parsing
    
    NullPointerException - if the argument list is null
  - isShortOptionDisabled
```
public boolean isShortOptionDisabled()
```

Class OptionParser

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

OptionParser

OptionParser

OptionParser

OptionParser

Method Detail

accepts

accepts

acceptsAll

acceptsAll

posixlyCorrect

recognizeAlternativeLongOptions

printHelpOn

printHelpOn

formatHelpWith

parse

isShortOptionDisabled