joptsimple
Class OptionParser

java.lang.Object
  extended by joptsimple.OptionParser
Direct Known Subclasses:
OptionParserNat

public class OptionParser
extends java.lang.Object

Parses command line arguments according to GNU's conventions.

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 internal domain-specific language begin with a call to accepts or acceptsAll methods on the ensuing chain of objects describe whether the options can take an argument, whether the argument is required or optional, and to what type arguments of the options should be converted.
  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:

     
     parser.acceptsAll(
         Arrays.asList( new String[] { "w", "interactive", "confirmation" } ) );
     OptionSet options = parser.parse( new String[] { "-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 ("+")

Since:
1.0
Version:
$Id: OptionParser.java,v 1.7 2008/05/01 15:38:45 pholser Exp $
Author:
Paul Holser
See Also:
The GNU C Library

Field Summary
private  boolean posixlyCorrect
           
private  AbbreviationMap recognizedOptions
           
private  OptionParserState state
           
 
Constructor Summary
OptionParser()
          Creates an option parser that initially recognizes no options, and does not exhibit "POSIX-ly correct" behavior.
OptionParser(java.lang.String optionSpecification)
          Creates an option parser and configures it to recognize the short options specified in the given string.
 
Method Summary
 OptionSpecBuilder accepts(java.lang.String option)
          Tells the parser to recognize the given option.
 OptionSpecBuilder accepts(java.lang.String option, java.lang.String description)
          Tells the parser to recognize the given option.
 OptionSpecBuilder acceptsAll(java.util.List options)
          Tells the parser to recognize the given options, and treat them as synonymous.
 OptionSpecBuilder acceptsAll(java.util.List options, java.lang.String description)
          Tells the parser to recognize the given options, and treat them as synonymous.
private static char[] extractShortOptionsFrom(java.lang.String argument)
           
(package private)  void handleLongOptionToken(java.lang.String candidate, ArgumentList arguments, OptionSet detected)
           
private  void handleShortOptionCluster(java.lang.String candidate, ArgumentList arguments, OptionSet detected)
           
(package private)  void handleShortOptionToken(java.lang.String candidate, ArgumentList arguments, OptionSet detected)
           
private  boolean isRecognized(java.lang.String option)
           
(package private)  boolean looksLikeAnOption(java.lang.String argument)
           
(package private)  void noMoreOptions()
           
 OptionSet parse(java.lang.String[] arguments)
          Parses the given command line arguments according to the option specifications given to the parser.
private static KeyValuePair parseLongOptionWithArgument(java.lang.String argument)
           
private static KeyValuePair parseShortOptionWithArgument(java.lang.String argument)
           
(package private)  boolean posixlyCorrect()
           
 void posixlyCorrect(boolean setting)
          Tells the parser whether or not to behave "POSIX-ly correct"-ly.
 void printHelpOn(java.io.OutputStream sink)
          Writes information about the options this parser recognizes to the given output sink.
 void printHelpOn(java.io.Writer sink)
          Writes information about the options this parser recognizes to the given output sink.
(package private)  void recognize(OptionSpec spec)
           
 void recognizeAlternativeLongOptions(boolean recognize)
          Tells the parser either to recognize or ignore "-W"-style long options.
private  void reset()
           
 void setPosixlyCorrect(boolean setting)
          Deprecated. Use posixlyCorrect(boolean) instead.
private  OptionSpec specFor(char option)
           
private  OptionSpec specFor(java.lang.String option)
           
private  void validateOptionCharacters(char[] options)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

recognizedOptions

private final AbbreviationMap recognizedOptions

state

private OptionParserState state

posixlyCorrect

private boolean posixlyCorrect
Constructor Detail

OptionParser

public OptionParser()

Creates an option parser that initially recognizes no options, and does not exhibit "POSIX-ly correct" behavior.

Since:
1.0

OptionParser

public OptionParser(java.lang.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:
java.lang.NullPointerException - if optionSpecification is null
OptionException - if the option specification contains illegal characters or otherwise cannot be recognized
Since:
1.0
Method Detail

accepts

public OptionSpecBuilder accepts(java.lang.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 an internal domain-specific 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
java.lang.NullPointerException - if the option is null
Since:
2.0

accepts

public OptionSpecBuilder accepts(java.lang.String option,
                                 java.lang.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
java.lang.NullPointerException - if the option is null
Since:
2.1
See Also:
accepts(String)

acceptsAll

public OptionSpecBuilder acceptsAll(java.util.List 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
java.lang.NullPointerException - if the option list or any of its elements are null
java.lang.ClassCastException - if any of the items in the option list is not a String
Since:
2.4
See Also:
accepts(String)

acceptsAll

public OptionSpecBuilder acceptsAll(java.util.List options,
                                    java.lang.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
java.lang.NullPointerException - if the option list or any of its elements are null
java.lang.IllegalArgumentException - if the option list is empty
java.lang.ClassCastException - if any of the items in the option list is not a String
Since:
2.4
See Also:
acceptsAll(List)

setPosixlyCorrect

public void setPosixlyCorrect(boolean setting)
Deprecated. Use posixlyCorrect(boolean) instead.

Tells the parser whether or not to behave "POSIX-ly correct"-ly.

Parameters:
setting - true if the parser should behave "POSIX-ly correct"-ly
Since:
1.0

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
Since:
2.4

posixlyCorrect

boolean posixlyCorrect()

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
Since:
1.0

recognize

void recognize(OptionSpec spec)

printHelpOn

public void printHelpOn(java.io.OutputStream sink)
                 throws java.io.IOException

Writes information about the options this parser recognizes to the given output sink.

Parameters:
sink - the sink to write information to
Throws:
java.io.IOException - if there is a problem writing to the sink
java.lang.NullPointerException - if sink is null
Since:
2.1

printHelpOn

public void printHelpOn(java.io.Writer sink)
                 throws java.io.IOException

Writes information about the options this parser recognizes to the given output sink.

Parameters:
sink - the sink to write information to
Throws:
java.io.IOException - if there is a problem writing to the sink
java.lang.NullPointerException - if sink is null
Since:
2.1

parse

public OptionSet parse(java.lang.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
java.lang.NullPointerException - if the argument list is null
Since:
1.0

handleLongOptionToken

void handleLongOptionToken(java.lang.String candidate,
                           ArgumentList arguments,
                           OptionSet detected)

handleShortOptionToken

void handleShortOptionToken(java.lang.String candidate,
                            ArgumentList arguments,
                            OptionSet detected)

handleShortOptionCluster

private void handleShortOptionCluster(java.lang.String candidate,
                                      ArgumentList arguments,
                                      OptionSet detected)

noMoreOptions

void noMoreOptions()

looksLikeAnOption

boolean looksLikeAnOption(java.lang.String argument)

isRecognized

private boolean isRecognized(java.lang.String option)

specFor

private OptionSpec specFor(char option)

specFor

private OptionSpec specFor(java.lang.String option)

reset

private void reset()

extractShortOptionsFrom

private static char[] extractShortOptionsFrom(java.lang.String argument)

validateOptionCharacters

private void validateOptionCharacters(char[] options)

parseLongOptionWithArgument

private static KeyValuePair parseLongOptionWithArgument(java.lang.String argument)

parseShortOptionWithArgument

private static KeyValuePair parseShortOptionWithArgument(java.lang.String argument)