public class CommandArgs extends Object implements Iterable<String>
COMMAND [ OPTION ... ] [ -- ] [ OTHER_ARGUMENT ... ]
([]'s indicate optional parts; ... indicates one or more). Each
OPTION has one of the following forms (x, y, etc. denote
non-blank characters):
Single parameterless short option:
-x
Several parameterless short options:
-xyz...
Single short option with parameter:
-x OPTARG
or
-xOPTARG
Long parameterless option:
--opt
Long option with parameter:
--opt=foo
If a short option takes an additional argument, that argument is
always required to follow; it cannot be omitted. When a long argument
takes an argument, it is optional.
The '--' before the first OTHER_ARGUMENT is optional unless that OTHER_ARGUMENT starts with '-'.
One creates a CommandArgs object by supplying a String describing the legal options, and an array of command-line argument strings (as sent to the main function).
The CommandArgs object then parses the command-line arguments according to the specification, and presents the options and other arguments as a mapping between option keys (like "--opt" or "-x") to lists of argument values supplied for that option in the command-line arguments (these are lists because in general, an option can appear several times). Options that take no arguments get the argument value "". Trailing arguments correspond to the option key "--".
Any short option is considered equivalent to a one-character long option, and vice-versa.
For example, suppose that we have a program whose usage is
foo [ -c ] [ -h ] [ -o FILE ] ARG1
where []'s indicate optional arguments, and there may be at most
one -o argument. It's main program would begin
import ucb.util.CommandArgs;
class foo {
public static void main(String[] args0) {
boolean cOptionSpecified;
boolean hOptionSpecified;
String oOptionValue;
List arg1;
CommandArgs args =
new CommandArgs("-c -h -o={0,1} --={1}", args0);
if (! args.ok())
ERROR();
cOptionSpecified = args.contains("-c");
hOptionSpecified = args.contains("-h");
oOptionValue = args.getLast("-o"); // null if absent.
arg1 = args.getFirst("--");
...
For a program whose usage is
bar [ -c ] [ -k COUNT ] [ --dry-run ] [ --form=NAME ] [ ARG ... ]
where there may be at most one -k option (which must be an integer),
any number of --form options, and zero or more trailing arguments, we
could write:
import ucb.util.CommandArgs;
class foo {
public static void main(String[] args0) {
...
String options = "-c -k=(\\d+){0,1} --dry-run --form="
+ "--={0,}";
;
CommandArgs args = new CommandArgs(options, args0);
...
int count;
if (args.contains("-k"))
count = args.getInt("-k");
List forms = args.get("--form");
List otherArgs = args.get("--");
One can group options into mutually exclusive choices using a trailing ":N" label, where N is a numeral identifying the group. Here is an example in which there must be exactly one occurrence of either the option -i, -q, or -l, an optional occurrence of either of the mutually-exclusive options -n or -N, up to 3 occurrences of options -a and -b in any combination, and no trailing arguments:
import ucb.util.CommandArgs;
class foo {
public static void main(String[] args0) {
...
String options = "-c{1}:1 -q:1 -l:1 -n{0,1}:2 -N:2 -a={0,3}:3 -b=:3";
CommandArgs args = new CommandArgs(options, args0);
...
By default, when an option has a value (indicated by = after the option
key), that value may be any string. You may also describe argument
values with general patterns in parentheses, using the
regular-expression patterns provided by the
Pattern class. For example, writing
CommandArgs args =
new CommandArgs("--flavor=(van(illa)?|choc(olate)?)", args0)
specifies any number of --flavor parameters, each of which may be
either 'vanilla' ('van' for short) or 'chocolate' ('choc' for short).
<option string> ::= <options> <trailing>
| <options> | <trailing>
<options> ::= <option> | <options> option>
<option> ::= <option pattern>
| <option pattern><repeat>
<option pattern> ::= <simple pattern>
| (<simple patterns>)
<simple pattern> ::=
<option key>
| <option key>=<pattern>
<option key> ::=
-<single graphic character other than ->
| --<graphic characters other than = not starting with ->
<simple patterns> ::=
<simple pattern>
| <simple patterns> `|' <simple pattern>
<repeat> ::=
<count> | <count> <label> | <label>
<count> ::=
{<integer>}
| {<integer>,<integer>}
| {<integer>,}
<label> ::= : <positive integer>
<trailing> ::= --=<pattern>
| --=<pattern><repeat>
<pattern> ::= <empty> | (<regular expression>)
<regular expression> is as described in the documentation
for Pattern. The default is `.+' (any
non-empty string).
A <repeat> clause limits the number of instances of a given option or trailing argument. When unspecified, it is "zero or more" ({0,}). A trailing <label> indicates a group of options that are mutually exclusive. The count that appears on the first option specification of the group applies to all (subsequent options should specify just the label part, not the { } part). At most one of the keys in any group may appear. The count applies to whichever one does.
No <option> may contain whitespace. Also, be careful of the usual escaping problems with representing regular expressions as java Strings. The regular expression \d, for example, is written as the String literal "\\d".
| Constructor and Description |
|---|
CommandArgs(String optionString,
String[] rawArgs)
A set of argument values extracted from RAWARGS according to
the description given in OPTIONSTRING.
|
| Modifier and Type | Method and Description |
|---|---|
boolean |
contains(String key)
Returns true iff option KEY is present.
|
boolean |
containsKey(String key)
Deprecated.
use
contains(String) instead. |
List<String> |
get(String key)
Return the list of all argument values for option KEY, or null if
the option does not appear.
|
String[] |
getArguments()
Return the argument array (not a copy) with which THIS was created.
|
double |
getDouble(String key)
Return the value of the last occurrence of option KEY, as
a floating-point value.
|
double |
getDouble(String key,
double dflt)
REturn the value of the last occurrence of option KEY, as
a floating-point value, or DFLT if KEY is not present.
|
String |
getFirst(String key)
The argument value of the first occurrence of option KEY, or null
if there is no occurrence, or it has the wrong format.
|
String |
getFirst(String key,
String dflt)
The argument value of the first occurrence of option KEY, or DFLT
if there is no occurrence, or it has the wrong format.
|
int |
getInt(String key)
Return The value of the last occurrence of option KEY, as a
decimal integer.
|
int |
getInt(String key,
int radix)
Return The value of the last occurrence of option KEY, as an integer of
given RADIX.
|
int |
getInt(String key,
int radix,
int dflt)
Return the value of the last occurrence of option KEY, as an integer of
given RADIX, or DFLT if KEY is not present.
|
String |
getLast(String key)
The argument value of the last occurrence of option KEY, or null
if there is no occurrence, or it has the wrong format.
|
String |
getLast(String key,
String dflt)
The argument value of the last occurrence of option KEY, or DFLT
if there is no occurrence, or it has the wrong format.
|
long |
getLong(String key)
Return the value of the last occurrence of option KEY, as a
decimal integer.
|
long |
getLong(String key,
int radix)
Return the value of the last occurrence of option KEY, as an integer of
given RADIX.
|
long |
getLong(String key,
int radix,
long dflt)
Return the value of the last occurrence of option KEY, as an integer of
given RADIX, or DFLT if KEY is not present.
|
String |
getOptionString()
Return the option string with which THIS was created.
|
Iterator<String> |
iterator()
Return An iterator over the set of keys in optionKeys().
|
int |
number(String key)
Return the number of occurrences of option key KEY.
|
boolean |
ok()
Return true iff all arguments were correct.
|
List<String> |
optionKeys()
Return a list of all keys that appeared in the arguments, in order of
appearance.
|
List<String> |
optionValues()
Return A list of all option values that appeared in the arguments,
in order of appearance.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitforEach, spliteratorpublic CommandArgs(String optionString, String[] rawArgs)
public String getOptionString()
public String[] getArguments()
public int number(String key)
public boolean contains(String key)
@Deprecated public boolean containsKey(String key)
contains(String) instead.public List<String> get(String key)
public String getFirst(String key)
public String getFirst(String key, String dflt)
public String getLast(String key, String dflt)
public String getLast(String key)
public int getInt(String key)
public int getInt(String key, int radix)
public int getInt(String key, int radix, int dflt)
NumberFormatException - if the value of option KEY is not
a valid numeral of radix RADIX, RADIX is not a valid RADIX, or
the number if out of range.public long getLong(String key)
public long getLong(String key, int radix)
public long getLong(String key, int radix, long dflt)
NumberFormatException - if the value of option KEY is not
a valid numeral of radix RADIX, RADIX is not a valid RADIX, or
the result is not in the range of long.public double getDouble(String key)
public double getDouble(String key, double dflt)
public boolean ok()
public List<String> optionKeys()
public List<String> optionValues()
public Iterator<String> iterator()
get(String),
getFirst(String), etc. to retrieve the value(s)
of an option.