joptsimple
Class OptionParser

java.lang.Object
  extended by joptsimple.OptionParser
All Implemented Interfaces:
OptionDeclarer

public class OptionParser
extends Object
implements OptionDeclarer

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.

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:

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 ("+")

Author:
Paul Holser
See Also:
The GNU C Library

Constructor Summary
OptionParser()
          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.
 
Method Summary
 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 allowsUnrecognizedOptions()
          Tells the parser to treat unrecognized options as non-option arguments.
 void formatHelpWith(HelpFormatter formatter)
          Tells the parser to use the given formatter when asked to print help.
 NonOptionArgumentSpec<String> nonOptions()
          Gives an object that represents an access point for non-option arguments on a command line.
 NonOptionArgumentSpec<String> nonOptions(String description)
          Gives an object that represents an access point for non-option arguments on a command line.
 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.
 Map<String,OptionSpec<?>> recognizedOptions()
          Retrieves all the options which have been configured for the parser.
 
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
Method Detail

accepts

public OptionSpecBuilder accepts(String option)
Description copied from interface: OptionDeclarer
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:


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

Specified by:
accepts in interface OptionDeclarer
Parameters:
option - the option to recognize
Returns:
an object that can be used to flesh out more detail about the option

accepts

public OptionSpecBuilder accepts(String option,
                                 String description)
Description copied from interface: OptionDeclarer
Tells the parser to recognize the given option.

Specified by:
accepts in interface OptionDeclarer
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
See Also:
OptionDeclarer.accepts(String)

acceptsAll

public OptionSpecBuilder acceptsAll(Collection<String> options)
Description copied from interface: OptionDeclarer
Tells the parser to recognize the given options, and treat them as synonymous.

Specified by:
acceptsAll in interface OptionDeclarer
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
See Also:
OptionDeclarer.accepts(String)

acceptsAll

public OptionSpecBuilder acceptsAll(Collection<String> options,
                                    String description)
Description copied from interface: OptionDeclarer
Tells the parser to recognize the given options, and treat them as synonymous.

Specified by:
acceptsAll in interface OptionDeclarer
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
See Also:
OptionDeclarer.acceptsAll(Collection)

nonOptions

public NonOptionArgumentSpec<String> nonOptions()
Description copied from interface: OptionDeclarer
Gives an object that represents an access point for non-option arguments on a command line.

Specified by:
nonOptions in interface OptionDeclarer
Returns:
an object that can be used to flesh out more detail about the non-option arguments

nonOptions

public NonOptionArgumentSpec<String> nonOptions(String description)
Description copied from interface: OptionDeclarer
Gives an object that represents an access point for non-option arguments on a command line.

Specified by:
nonOptions in interface OptionDeclarer
Parameters:
description - a string that describes the purpose of the non-option arguments. This is used when generating help information about the parser.
Returns:
an object that can be used to flesh out more detail about the non-option arguments
See Also:
OptionDeclarer.nonOptions()

posixlyCorrect

public void posixlyCorrect(boolean setting)
Description copied from interface: OptionDeclarer
Tells the parser whether or not to behave "POSIX-ly correct"-ly.

Specified by:
posixlyCorrect in interface OptionDeclarer
Parameters:
setting - true if the parser should behave "POSIX-ly correct"-ly

allowsUnrecognizedOptions

public void allowsUnrecognizedOptions()
Description copied from interface: OptionDeclarer

Tells the parser to treat unrecognized options as non-option arguments.

If not called, then the parser raises an OptionException when it encounters an unrecognized option.

Specified by:
allowsUnrecognizedOptions in interface OptionDeclarer

recognizeAlternativeLongOptions

public void recognizeAlternativeLongOptions(boolean recognize)
Description copied from interface: OptionDeclarer
Tells the parser either to recognize or ignore "-W"-style long options.

Specified by:
recognizeAlternativeLongOptions in interface OptionDeclarer
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

recognizedOptions

public Map<String,OptionSpec<?>> recognizedOptions()
Retrieves all the options which have been configured for the parser.

Returns:
a Map containing all the configured options and their corresponding OptionSpec

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


Copyright © 2014. All Rights Reserved.