Lightweight Bartering Grid

lbg.common.io
Class ArgsParser

java.lang.Object
  extended by lbg.common.io.ArgsParser

public class ArgsParser
extends java.lang.Object

A parser for command-line arguments.
Supports optional and required parameters, short and long options, flags and arguments taking a list of values.
Currently doesn't support arguments strings with a inderminate number of parameters at the end (like a list of files grep-style). Can be easily bypassed with a OptionType.LIST option.

Version history

1.1.3 (2007-03-27)
addIntOption(char, String, boolean, Integer, String) requires a default value if option isn't required.
1.1.2 (2006-12-01)
Check passed parameters.
1.1.1 (2006-10-17)
Usage auto-documents LISTs if needed.
1.1 (2006-10-15)
Added support for lists.
1.0.1 (2006-08-27)
Improved the looks of usage information.
1.0 (2006-08-26)
First working version, added support for custom helper, see addHelper() ; descriptions ; improved usage information ; still lacks lists.
0.1.1
Support for types.
0.1.0
Objectives, method signatures and main structures.

Todo:

Version:
1.1.3 (2007-03-27)
Author:
Xavier Dalem

Constructor Summary
ArgsParser(java.lang.String program)
          Prepare an argument parser.
 
Method Summary
 void addFlag(char sh, java.lang.String lg, java.lang.String desc)
          Register a flag for the Arguments Parser.
 void addHelper(char sh, java.lang.String lg, java.lang.String desc)
          Adds a special kind of flag that will cause the parser to stop without paying attention to the rest of the command line.
 void addIntOption(char sh, java.lang.String lg, boolean required, java.lang.Integer defValue, java.lang.String desc)
          Register an int option for the Arguments Parser.
 void addListOption(char sh, java.lang.String lg, boolean required, java.lang.String desc)
          Register an list option for the Arguments Parser.
 void addStringOption(char sh, java.lang.String lg, boolean required, java.lang.String defValue, java.lang.String desc)
          Register a string option for the Arguments Parser.
 boolean getFlag(char sh)
          Get value of flag sh.
 boolean getFlag(java.lang.String lg)
          Get value of flag lg.
 int intValueOf(char sh)
          Get value of option sh as an int.
 int intValueOf(java.lang.String lg)
          Get value of option lg as an int.
 java.lang.String[] listValueOf(char sh)
          Get value of option sh as a string array.
 java.lang.String[] listValueOf(java.lang.String lg)
          Get value of option lg as a string array.
static void main(java.lang.String[] argv)
          Demo program for ArgsParser
 void parse(java.lang.String[] argv)
          Parse the arguments with currently registered options and flags
 java.lang.String strValueOf(char sh)
          Get value of option sh.
 java.lang.String strValueOf(java.lang.String lg)
          Get value of option lg.
 java.lang.String usage()
          Returns usage infomation, to be printed in console or screen.
 
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 program)
Prepare an argument parser.

Parameters:
program - The program name, as it will appear in usage information
Method Detail

addStringOption

public void addStringOption(char sh,
                            java.lang.String lg,
                            boolean required,
                            java.lang.String defValue,
                            java.lang.String desc)
                     throws lbg.common.io.ArgsParser.OptionException
Register a string option for the Arguments Parser.

Parameters:
sh - The short option character (for -f options), ' ' if none
lg - The long option string, without first leading '-'. For '--foo' style options, make only one leading '-', null if none
required - true if the option is required
defValue - The default value for that option, null for none. Not taken into account if option is required.
desc - A description in usage information
Throws:
OptionException - In case of option inconsistency
lbg.common.io.ArgsParser.OptionException

addListOption

public void addListOption(char sh,
                          java.lang.String lg,
                          boolean required,
                          java.lang.String desc)
                   throws lbg.common.io.ArgsParser.OptionException
Register an list option for the Arguments Parser. Default values aren't supported. The list is a comma-separated list of string values.

Parameters:
sh - The short option character (for -f options), ' ' if none
lg - The long option string, without first leading '-'. For '--foo' style options, make only one leading '-', null if none
required - true if the option is required
desc - A description in usage information
Throws:
OptionException - In case of option inconsistency
lbg.common.io.ArgsParser.OptionException

addIntOption

public void addIntOption(char sh,
                         java.lang.String lg,
                         boolean required,
                         java.lang.Integer defValue,
                         java.lang.String desc)
                  throws lbg.common.io.ArgsParser.OptionException
Register an int option for the Arguments Parser.

Parameters:
sh - The short option character (for -f options), ' ' if none
lg - The long option string, without first leading '-'. For '--foo' style options, make only one leading '-', null if none
required - true if the option is required
defValue - The default value for that option. Not taken into account if option is required.
desc - A description in usage information
Throws:
OptionException - In case of option inconsistency
lbg.common.io.ArgsParser.OptionException

addFlag

public void addFlag(char sh,
                    java.lang.String lg,
                    java.lang.String desc)
             throws lbg.common.io.ArgsParser.OptionException
Register a flag for the Arguments Parser. Flags do not require an argument, and are always optionnal.

Parameters:
sh - The short option character (for -f options), ' ' if none
lg - The long option string, without first leading '-'. For '--foo' style options, make only one leading '-', null if none
desc - A description in usage information
Throws:
OptionException - In case of option inconsistency
lbg.common.io.ArgsParser.OptionException

addHelper

public void addHelper(char sh,
                      java.lang.String lg,
                      java.lang.String desc)
               throws lbg.common.io.ArgsParser.OptionException
Adds a special kind of flag that will cause the parser to stop without paying attention to the rest of the command line. Nothing will be done but setting the appropriate flag.
Only one helper can be set

Parameters:
sh - The short option character (for -f options), ' ' if none
lg - The long option string, without first leading '-'. For '--foo' style options, make only one leading '-', null if none
desc - A description in usage information
Throws:
OptionException - In case of option inconsistency
lbg.common.io.ArgsParser.OptionException

parse

public void parse(java.lang.String[] argv)
           throws java.text.ParseException
Parse the arguments with currently registered options and flags

Parameters:
argv - The arguments to parse
Throws:
java.text.ParseException - if parsing fails. Offset from that exception is the number of the argument

strValueOf

public java.lang.String strValueOf(java.lang.String lg)
                            throws lbg.common.io.ArgsParser.OptionException
Get value of option lg. If that option was also registered with a character, you may indiferently check both and get the same result.
This value is guaranteed to be non null if option was required and parse() didn't throw an exception.

Parameters:
lg - The long option
Throws:
OptionException - If the option doesn't exist
lbg.common.io.ArgsParser.OptionException

strValueOf

public java.lang.String strValueOf(char sh)
                            throws lbg.common.io.ArgsParser.OptionException
Get value of option sh. If that option was also registered with a string, you may indiferently check both and get the same result.
This value is guaranteed to be non null if option was required and parse() didn't throw an exception.
This method can be more efficient than its equivalent taking a String as first argument.

Parameters:
sh - The short option
Throws:
OptionException - If the option doesn't exist
lbg.common.io.ArgsParser.OptionException

listValueOf

public java.lang.String[] listValueOf(java.lang.String lg)
                               throws lbg.common.io.ArgsParser.OptionException
Get value of option lg as a string array. If that option was also registered with a character, you may indiferently check both and get the same result.
This value is guaranteed to be non null if option was required and parse() didn't throw an exception.

Parameters:
lg - The long option
Throws:
OptionException - If the option doesn't exist
lbg.common.io.ArgsParser.OptionException

listValueOf

public java.lang.String[] listValueOf(char sh)
                               throws lbg.common.io.ArgsParser.OptionException
Get value of option sh as a string array. If that option was also registered with a string, you may indiferently check both and get the same result.
This value is guaranteed to be non null if option was required and parse() didn't throw an exception.
This method can be more efficient than its equivalent taking a String as first argument.

Parameters:
sh - The short option
Throws:
OptionException - If the option doesn't exist
lbg.common.io.ArgsParser.OptionException

intValueOf

public int intValueOf(java.lang.String lg)
               throws lbg.common.io.ArgsParser.OptionException
Get value of option lg as an int. If that option was also registered with a character, you may indiferently check both and get the same result.
This method gets through the task of typecasting the argument.
This value is guaranteed to exist if option was required and parse() didn't throw an exception.

Parameters:
lg - The long option
Throws:
OptionException - If the option doesn't exist
lbg.common.io.ArgsParser.OptionException

intValueOf

public int intValueOf(char sh)
               throws lbg.common.io.ArgsParser.OptionException
Get value of option sh as an int. If that option was also registered with a character, you may indiferently check both and get the same result.
This method gets through the task of typecasting the argument.
This value is guaranteed to exist if option was required and parse() didn't throw an exception.
This method can be more efficient than its equivalent taking a String as first argument.

Parameters:
sh - The short option
Throws:
OptionException - If the option doesn't exist
lbg.common.io.ArgsParser.OptionException

getFlag

public boolean getFlag(java.lang.String lg)
                throws lbg.common.io.ArgsParser.OptionException
Get value of flag lg. If that option was also registered with a character, you may indiferently check both and get the same result.
This value is guaranteed to exist.

Parameters:
lg - The long option
Returns:
true if the flag was present
Throws:
OptionException - If the option doesn't exist
lbg.common.io.ArgsParser.OptionException

getFlag

public boolean getFlag(char sh)
                throws lbg.common.io.ArgsParser.OptionException
Get value of flag sh. If that option was also registered with a character, you may indiferently check both and get the same result.
This value is guaranteed to exist.
This method can be more efficient than its equivalent taking a String as first argument.

Parameters:
sh - The short option
Returns:
true if the flag was present
Throws:
OptionException - If the option doesn't exist
lbg.common.io.ArgsParser.OptionException

usage

public java.lang.String usage()
Returns usage infomation, to be printed in console or screen. This command also outputs the format of LISTs, so it shouldn't be mentionned in independant descriptions.


main

public static void main(java.lang.String[] argv)
                 throws lbg.common.io.ArgsParser.OptionException
Demo program for ArgsParser

Throws:
lbg.common.io.ArgsParser.OptionException

Lightweight Bartering Grid

Copyright (c) 2005-2008, Cyril Briquet, parts Xavier Dalem.