edu.mines.jtk.util
Class ArgsParser

java.lang.Object
  edu.mines.jtk.util.ArgsParser

public class ArgsParser
extends java.lang.Object

Parses command-line arguments for options and values, using conventions like those used by the UNIX function getopt; e.g., "-a". Also supports GNU-style long options; e.g., "--alpha".

Short options in command-line arguments have the form "-a". A short options may have a value, as in "-a3.14" or "-a 3.14". Multiple short options without values may be specified together, so that "-ab" is equivalent to "-a -b". (Note that if a value is expected for option "-a", then "-ab" specifies "b" as that value.)

Long options in command-line arguments have the form "--alpha". A long option may also have a value, as in "--alpha=3.14" or "--alpha 3.14". Long option names may be abbreviated, provided that the abbreviation is unique among all long options. For example, "--a=3.14" is equivalent to "--alpha=3.14", provided that no other long option begins with "--a".

For both short and long options, it is an error to specify a value where one is not expected, or to omit a value where one is expected.

Option parsing ends with the first argument that is not an option, i.e., one that does not begin with a hyphen "-". As a special case, parsing also ends after the special option "--".

Typical usage within the standard method main is:

 public static void main(String[] args) {
   float a = 3.14f;
   boolean b = false;
   String fileName = null;
   try {
     String shortOpts = "ha:b";
     String[] longOpts = {"help","alpha=","beta"};
     ArgsParser ap = new ArgsParser(args,shortOpts,longOpts);
     String[] opts = ap.getOptions();
     String[] vals = ap.getValues();
     for (int i=0; i<opts.length; ++i) {
       String opt = opts[i];
       String val = vals[i];
       if (opt.equals("-h") || opt.equals("--help")) {
         printUsageAndExit(0);
       } else if (opt.equals("-a") || opt.equals("--alpha")) {
         a = ap.toFloat(val);
       } else if (opt.equals("-b") || opt.equals("--beta")) {
         b = true;
       }
     }
     args = ap.getOtherArgs();
     if (args.length!=1)
       printUsageAndExit(-1);
     fileName = args[0];
   } catch (OptionException oe) {
     System.err.println(oe.getMessage());
     printUsageAndExit(-1);
   }
   // ...
 }
 

Version:

2001.02.04, 2006.07.12

Author:

Dave Hale, Colorado School of Mines

Nested Class Summary

static class

ArgsParser.OptionException Option exceptions are thrown when options specified in arguments are inconsistent with the parser's specifications.

Constructor Summary

ArgsParser(java.lang.String[] args, java.lang.String shortOpts)
Constructs an argument parser for the specified arguments and short options specification.

ArgsParser(java.lang.String[] args, java.lang.String shortOpts, java.lang.String[] longOpts)
Constructs an argument parser for the specified arguments and short and long options specifications.

Method Summary

java.lang.String[]	getOptions() Gets the options parsed.
java.lang.String[]	getOtherArgs() Gets the other arguments, those that do not correspond to options.
java.lang.String[]	getValues() Gets the values corresponding to the options parsed.
static boolean	toBoolean(java.lang.String s) Converts a string value to a boolean.
static double	toDouble(java.lang.String s) Converts a string value to a double.
static float	toFloat(java.lang.String s) Converts a string value to a float.
static int	toInt(java.lang.String s) Converts a string value to an int.
static long	toLong(java.lang.String s) Converts a string value to a long.

Methods inherited from class java.lang.Object

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

Constructor Detail

ArgsParser

public ArgsParser(java.lang.String[] args,
                  java.lang.String shortOpts)
           throws ArgsParser.OptionException

Constructs an argument parser for the specified arguments and short options specification.

Parameters:

args - the command-line arguments, as passed to the method main.

shortOpts - the short options specification. Each option is specified by a single character. For options that require values, this character must be followed by a single colon ':'. For example, "a:b" specifies two options "-a" and "-b", and the first option "-a" requires a value.

Throws:

ArgsParser.OptionException

ArgsParser

public ArgsParser(java.lang.String[] args,
                  java.lang.String shortOpts,
                  java.lang.String[] longOpts)
           throws ArgsParser.OptionException

Constructs an argument parser for the specified arguments and short and long options specifications.

Parameters:

args - the command-line arguments, as passed to the method main.

shortOpts - the short options specification. Each option is specified by a single character. For options that require values, this character must be followed by a single colon ':'. For example, "a:b" specifies two options "-a" and "-b", and the first option "-a" requires a value.

longOpts - the long options specification. Each option is is specified by a single string, containing the long option name. For options that require values, this string must end in the character "=". For example, the string "--alpha=" specifies a long option "--alpha" that requires a value.

Throws:

ArgsParser.OptionException

Method Detail

getOptions

public java.lang.String[] getOptions()

Gets the options parsed.

Returns:

the options parsed. Each string is of the form "-a", for short options, or "--alpha", for long options. Note that the hyphen "-" or double-hyphen "--" is included in the strings. For long options, the complete names are returned, even if abbreviations were parsed.

getValues

public java.lang.String[] getValues()

Gets the values corresponding to the options parsed.

Returns:

the values parsed. The value is null for any option that does not expect a value.

getOtherArgs

public java.lang.String[] getOtherArgs()

Gets the other arguments, those that do not correspond to options.

Returns:

the other arguments.

toBoolean

public static boolean toBoolean(java.lang.String s)
                         throws ArgsParser.OptionException

Converts a string value to a boolean.

Parameters:

s - the string value.

Returns:

the boolean.

Throws:

ArgsParser.OptionException - if the string is not a valid boolean.

toDouble

public static double toDouble(java.lang.String s)
                       throws ArgsParser.OptionException

Converts a string value to a double.

Parameters:

s - the string value.

Returns:

the double.

Throws:

ArgsParser.OptionException - if the string is not a valid double.

toFloat

public static float toFloat(java.lang.String s)
                     throws ArgsParser.OptionException

Converts a string value to a float.

Parameters:

s - the string value.

Returns:

the float.

Throws:

ArgsParser.OptionException - if the string is not a valid float.

toInt

public static int toInt(java.lang.String s)
                 throws ArgsParser.OptionException

Converts a string value to an int.

Parameters:

s - the string value.

Returns:

the int.

Throws:

ArgsParser.OptionException - if the string is not a valid int.

toLong

public static long toLong(java.lang.String s)
                   throws ArgsParser.OptionException

Converts a string value to a long.

Parameters:

s - the string value.

Returns:

the long.

Throws:

ArgsParser.OptionException - if the string is not a valid long.