com.dynamide.util
Class Opts

java.lang.Object
  extended by com.dynamide.util.Opts

public class Opts
extends java.lang.Object

This class handles one command line options style: All options must begin with a dash. In this documentation, "switch" is the same as "option", but refers specifically to the token with the dash. Dashes may be single or double:

    -foo or --foo
Values may not have dashes. E.g.
   myprogram -foo -bar -file ./myfile -user "laramie" 

Note the two types of arguments:

The simplest way to think of this class is:

More details follow:


Boolean arguments can appear anywhere in the command line. Any switch that is followed by another switch is considered a boolean argument. (Except that anything after -- is not considered a switch).

To end switched arguments, uses "--" by itself, then any remaining arguments. The remaining arguments can then be retrieved by a call to getRemainingArgs(), which returns a String[]. e.g.,

    -foo -bar mojo -- nixon finbar
sets up a command line where calling getRemainingArgs() would retrieve {"nixon", "finbar"} as a Java String array. Parameters after -- can begin with dashes.

If you follow the rules, you don't need to use -- to begin the list of remaining args. If command line is "java myclass -foo a b a", remaining args will be "b" and "a", unless you call addOption("-foo", Boolean.class, false) or addOption("-foo", Boolean.class, true) then remaining args is "a", "b", and "c".

Alternatively, you can call getOptionList() to get the list of arguments at the end, or getOptionList(key) to see the non-switch arguments after "key", EVEN if you have defined "key" to be boolean. See examples at those methods. The getOptionList(key) method enables you to use embedded lists:

         -list1 a b c -list2 d e f

You cannot group option letters: "-abc" cannot be construed as options "a", "b", and "c" all being true. In this version, you must specify such options as "-a -b -c"

You can have spaces in the values if the Java VM on your platform and you shell handle spaces in quotes, by putting quotes around option values. In csh, etc., you can use single or double quotes, in NT CMD you must use double quotes.

This style is not supported: -b12 where this implies option "b" == 12.

If addOption is called, the options will be rescanned with the new rules before the next access of any option. You can also call validate() after addOption and the new rules will apply.

If the form you need to process is "java MyClass -foo a b c", then you have three options: the default behavior is that -foo will be a String type and getOptionList will return {"b", "c"} as an array; this will also be the behavior if you call addOption("-foo", String.class) or addOption("-foo", String.class, true); else you can call addOption("-foo", Boolean.class) etc., in which case getOptionList will return {"a", "b", "c"}

 Example usage:
       Opts opts = new Opts(args);
       String iniFile = opts.getOption("-ini", "");
       if ( iniFile.length()==0 ) {
           usage();
       }
       String foo = opts.getOption("-foo");
       int ifoo = opts.getOptionInt("-foo", 4);
       System.out.println("getOptionBool(\"-bar\")="
                +opts.getOptionBool("-bar");
       String[] lastArgs = opts.getOptionList("");
       String [] list = opts.getOptionList("-list");

 Example 2:
       Opts opts = new Opts(args);
       opts.addOption("-foo", Integer.class, true);
       opts.addOption("-bar", true);
       String err = opts.validate();
       if ( err.length()>0 ) {
           System.out.println(err);
           System.exit(1);
       }
 

For more examples, see com.dynamide/util/Opts.java and run the default test cases:

  java com.dynamide.util.Opts
or run your own tests:
  java com.dynamide.util.Opts -my -test -case foo bar


Nested Class Summary
 class Opts.Option
           
 
Constructor Summary
Opts(java.lang.String[] args)
           
 
Method Summary
 void addOption(java.lang.String key, java.lang.Class type, boolean required)
          Declare options to have types and be required/optional.
 java.lang.String dump()
           
 java.lang.String getArgAt(int index)
           
 java.lang.String getOption(java.lang.String opt)
          Get the string value of option named by key, else return. "" Also, allow getOption("foo") and getOption("-foo").
 java.lang.String getOption(java.lang.String key, java.lang.String defaultValue)
          Get the string value of option named by key, else return default e.g.
 boolean getOptionBool(java.lang.String opt)
          Return true if option present, false if option is absent.
 int getOptionInt(java.lang.String opt, int defaultValue)
          Return integer value if option present and option parameter is a legal integer string.
 java.lang.String[] getOptionList()
          Same as calling getOptionList("");
 java.lang.String[] getOptionList(java.lang.String key)
          Gets the option list specified by key, that is, all the args after -key until next "-" (start of a switch or --) or the end.
 java.lang.String getRemainingArgAt(int index)
           
 java.lang.String[] getRemainingArgs()
          This is always the last arguments on the command line that are not switches, except that the leading value may be "consumed" by a String switch.
 int length()
           
static void main(java.lang.String[] args)
          Calls lots of test cases if called with no command line args, else processes command line args and shows some tests and a dump of processed state.
 java.lang.String toString()
           
 java.lang.String validate()
          Call to getting the first error string when validatating based on parameter types and requirements passed in addOption.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Opts

public Opts(java.lang.String[] args)
Method Detail

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

length

public int length()

getOption

public java.lang.String getOption(java.lang.String key,
                                  java.lang.String defaultValue)
Get the string value of option named by key, else return default e.g.
with {"-foo", "mojo"}, getOption("-foo", "bar") returns "mojo"
with {"-moxie", "mojo"}, getOption("-foo", "bar") returns "bar"


getOption

public java.lang.String getOption(java.lang.String opt)
Get the string value of option named by key, else return. "" Also, allow getOption("foo") and getOption("-foo"). e.g.
with {"-foo", "mojo"}, getOption("-foo") returns "mojo"
with {"-moxie", "mojo"}, getOption("-foo") returns ""


getOptionBool

public boolean getOptionBool(java.lang.String opt)
Return true if option present, false if option is absent. Also, allow getOptionBool("foo") and getOptionBool("-foo").
example
with {"-foo", "-mojo"}, getOptionBool("-foo") returns "true"
with {"-foo", "-mojo"}, getOptionBool("-bar") returns "false"
with {"-foo", "a", "-mojo"}, getOptionBool("-bar") returns "true" , even though "a" is adjacent -- with booleans, following parameters don't apply.


getOptionInt

public int getOptionInt(java.lang.String opt,
                        int defaultValue)
Return integer value if option present and option parameter is a legal integer string. Returns default value if option absent or option parameter is not a legal integer string. e.g.
with {"-foo", "-mojo"}, getOptionInt("-foo", 3) returns 3
with {"-foo", "20"}, getOptionInt("-foo") returns 20
with {"-foo", "20"}, getOptionBool("-bar") returns 3 .


getOptionList

public java.lang.String[] getOptionList()
Same as calling getOptionList("");


getOptionList

public java.lang.String[] getOptionList(java.lang.String key)
Gets the option list specified by key, that is, all the args after -key until next "-" (start of a switch or --) or the end.

For example:
java MyClass -list a b c -foo mojo 
getOptionList("-list") ==> a b c 
getOptionList() ==> []
getOptionList("-foo") ==> mojo


Example2:
java MyClass -list a b c -foo mojo nixon
getOptionList("-list") ==> a b c 
getOptionList() ==> nixon
getOptionList("-foo") ==> mojo nixon


Example3:
java MyClass a b c , then  
getOptionList("") ==> a b c  


Example3 is the same as calling the getOptionList() overload.


getRemainingArgs

public java.lang.String[] getRemainingArgs()
This is always the last arguments on the command line that are not switches, except that the leading value may be "consumed" by a String switch.

If you have something like "-foo a b", and -foo is not declared to be Boolean by a call to addOption(), then b is "remaining", (and -foo will have the value "a").

To explicitly make -foo be Boolean, call addOption("-foo", Boolean.class)

To explicitly make "a" and "b" both be "remaining" without declaring them, require the command-line user to put a -- in front: -foo -- a b

Another example: "-foo -bar mo -- mojo nixon", where "mo" is the value of switch "-bar", and the two arguments "mojo" and "nixon" would be the remaining args.

If you need to get lists (adjacent parameters without dashes_, either at the end or in the middle of the command-line, see getOptionList(String key).


getRemainingArgAt

public java.lang.String getRemainingArgAt(int index)

getArgAt

public java.lang.String getArgAt(int index)

addOption

public void addOption(java.lang.String key,
                      java.lang.Class type,
                      boolean required)
Declare options to have types and be required/optional. These are used in validate(), and to determine parsing order. The most important parse change is that Boolean.class types will never "consume" the non-switch parameters that follow them. Boolean are "stand-alone". For example: with "-foo a -bar b", if -foo is declared to be Boolean.class, then getOption("-foo") will return true, since -foo is present. -foo's value is NOT "a". By default, -foo would be String.class, and so getOption("-foo"); would return "a".

Parameters:
type - A Class type -- Legal values are: Boolean.class, Integer.class, and String.class

validate

public java.lang.String validate()
Call to getting the first error string when validatating based on parameter types and requirements passed in addOption.


dump

public java.lang.String dump()

main

public static void main(java.lang.String[] args)
Calls lots of test cases if called with no command line args, else processes command line args and shows some tests and a dump of processed state.



Copyright 2001-2013 DYNAMIDE.COM. All Rights Reserved.