|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectfc.util.Args
public class Args
Manages arguments passed to an application. Arguments can be optional or required. Arguments received by this class have to be either of the following formats:
-flagname1 value -flagname2=value2 .Arguments consist of flag name and flag value pairs. All flags must begin with a '-' character and any new word beginning with a '-' character is seen as the start of a new flag name (the '-' character is always permissible inside a token, i.e., after the first character). Additionaly, a flag name is delimited from it's corresponding value by either a space or the '=' character.
Note, in the above example, - flagname1 is separated from it's value by a space whereas - flagname2 is seperated from it's value by a '=' character. Both delimiters are valid and can be intermixed on the same line.
Note also that if the delimiter is a space, then the value part cannot begin with the - character, but if the delimiter is =, then the value part can begin with the - character. That is, the following input is valid:
-flagname1=-value-for-flag1
whereas this is invalid:
-flagname1 -value-for-flag1Here, -value-for-flag1 is seen as a new flag itself.
Following a flag name, all following values are assigned to that flagname, up until another flagname is encountered or the end of input is reached. Therefore, spaces do not have to be quoted. The following example,
-path \some file\some where else -port 80is parsed as:
Different operating systems (and their command interpreters) also transform/modify command lines in various ways. This class (and Java/JVM) can only parse arguments that it recieves from the operating system and those may be different than what you may have specified on the command line, due to the aforementioned transformation. The following example,
-path "/foo/bar /baz" -anotherpath \"a/b c/\"is parsed as:
bash
for example tokenizes the lines
using the IFS variable, and then feeds the tokens (separated by space) to the
invoked program, in this case, the java interpreter.
Sometimes flags are specified without any corresponding value, with the
existence of the flag itself implying some condition. However for clarity,
it's sometimes better to explicitly set an option to yes or no. Therefore
instead of saying -flag, always say -flag=[yes|no], with
the value part being "yes" or "no". However, the existence of the flag by
itself can be simply checked by using the flagExists()
method.
Typical usage of this class may look like:
Field Summary | |
---|---|
static java.lang.String |
DEFAULT_FLAGNAME
If a flag name is not well formed, then the corresponding value (if any) is stored under this name. |
static java.lang.String |
FLAG_REPEAT_VALUE_DELIM
If a flag name is repeated, then all corresponding values for that name are concatenated with each other and the concatenated values are delimited by this value. |
Constructor Summary | |
---|---|
Args(java.io.InputStream in)
Creates a new instance, with the specified InputStream to read arguments from. |
|
Args(java.lang.String[] args)
Creates a new instance, with the specified String[] to read arguments from. |
Method Summary | |
---|---|
boolean |
flagExists(java.lang.String flagname)
Checks if the specified flag exits, regardless of whether a corresponding value exist for that flag. |
java.lang.String |
get(int n)
Returns an argument by positional value. |
java.lang.String |
get(java.lang.String flagname)
Returns the value corresponding to the specified flag. |
java.lang.String |
get(java.lang.String flagname,
java.lang.String backup)
Returns the value corresponding to the specified flag. |
boolean |
getBoolean(java.lang.String flagname,
boolean backup)
Returns the value corresponding to the specified flag. |
int |
getFlagCount()
Returns the total number of flags available |
java.util.Date |
getFriendlyDate(java.lang.String flagname)
Returns the value as a Date. |
int |
getInt(java.lang.String flagname,
int backup)
Returns the value corresponding to the specified flag. |
long |
getLong(java.lang.String flagname,
long backup)
Returns the value corresponding to the specified flag. |
java.lang.String |
getMainClassName()
Returns the fully qualified name of the class that contained the main() method used to invoke the application. |
java.lang.String |
getRequired(int n)
Returns a required argument by positional value. |
java.lang.String |
getRequired(java.lang.String flagname)
Returns the value corresponding to the specified flag. |
boolean |
getRequiredBoolean(java.lang.String flagname)
|
java.io.File |
getRequiredFile(java.lang.String flagname)
Returns the value obtained via getRequired(String) as a File. |
java.util.Date |
getRequiredFriendlyDate(java.lang.String flagname)
Returns the value as a Date. |
int |
getRequiredInt(java.lang.String flagname)
|
int |
getRequiredInteger(java.lang.String flagname)
another alias for getRequiredInt(String) |
long |
getRequiredLong(java.lang.String flagname)
|
java.lang.String |
getRequiredString(java.lang.String flagname)
another alias for getRequired(String) |
void |
isMutuallyExclusive(java.lang.String... flags)
Checks to see that one and only 1 of the specified flags is present. |
static void |
main(java.lang.String[] args)
|
void |
onlyOneOf(java.lang.String... flags)
Checks to see that one and only 1 of the specified flags is present. |
java.lang.String[] |
rawValues()
Returns the raw String[] passed to this object during construction. |
void |
setDefaultUsage(java.lang.Object caller)
Convenience method to display the usage information in case of program error. |
void |
setDefaultUsage(java.lang.String pathToFile)
Convenience method to display the usage information in case of program error. |
void |
setUsage(java.lang.String str)
Specify program usage information to be output when an error occurs. |
void |
showError()
Invoking this method gives the same results as invoking getRequired with a non-existent flag name. |
java.util.Map |
values()
Returns a Map containing all flagname/flagvalue pairs. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static java.lang.String DEFAULT_FLAGNAME
- abcis missing a flagname ('-' followed by whitespace), therefore the value abc is stored under this default name.
public static java.lang.String FLAG_REPEAT_VALUE_DELIM
-foo abc -foo xyzhas the same flag repeated twice (foo) and the resulting value for this flag will be
abc,xyz
Constructor Detail |
---|
public Args(java.lang.String[] args)
public Args(java.io.InputStream in)
Method Detail |
---|
public boolean flagExists(java.lang.String flagname)
-foo -bar=baz. Then the flag foo would exist but have no corresponding value.
flagname
- the flagname to check
public int getFlagCount()
public java.lang.String getMainClassName()
public java.lang.String get(int n)
n
- the 0-based index of the String[] passed to main()
java.lang.NullPointerException
- if the specified index is greater than the number
of argumentspublic java.lang.String getRequired(int n)
getRequired(String)
n
- the 0-based index of the String[] passed to main()public java.lang.String get(java.lang.String flagname)
flagname
- the name of the flag without the leading - character
public java.lang.String get(java.lang.String flagname, java.lang.String backup)
flagname
- the name of the flag without the leading - characterbackup
- the value to return if flag not found
public boolean getBoolean(java.lang.String flagname, boolean backup)
yes, 1, true
else false is returned. Also seeflagExists(java.lang.String)
.
- Parameters:
flagname
- the name of the flag without the leading - characterbackup
- value to return if the property for the specified property is not present- Returns:
- value of specified key or backup string
public int getInt(java.lang.String flagname, int backup)
Integer.parseInt(String)
call),
the backup value will be returned.
flagname
- the name of the flag without the leading - characterbackup
- value to return if the property for the specified property is not
present
public long getLong(java.lang.String flagname, long backup)
Long.parseLong(String)
call),
the backup value will be returned.
flagname
- the name of the flag without the leading - characterbackup
- value to return if the property for the specified property is not
present
public java.lang.String getRequired(java.lang.String flagname)
error method
, which by default prints a
stack trace and exits the application.
If the handleError method is overriden to not exit the application, then this method will return null if the specified flag is not found.
flagname
- the name of the flag without the leading '-' character
handleError(java.lang.String)
public java.lang.String getRequiredString(java.lang.String flagname)
getRequired(String)
public boolean getRequiredBoolean(java.lang.String flagname)
public java.io.File getRequiredFile(java.lang.String flagname)
getRequired(String)
as a File.
If the handleError method is overriden to not exit the application, then this method will return false if the specified file does not exist.
public int getRequiredInt(java.lang.String flagname)
public int getRequiredInteger(java.lang.String flagname)
getRequiredInt(String)
public long getRequiredLong(java.lang.String flagname)
public java.util.Date getRequiredFriendlyDate(java.lang.String flagname)
If none of these special keywords are found, returns the value by trying to parsing it as: yyyy-MM-dd HH:mm:ss or yyyy-MM-dd
If the date cannot be parsed using either of the above patterns, an exception is thrown.
public java.util.Date getFriendlyDate(java.lang.String flagname)
If none of these special keywords are found, returns the value by trying to parsing it as: yyyy-MM-dd HH:mm:ss or yyyy-MM-dd
The flag is optional but if it is present and cannot be parsed using either of the above patterns, an exception is thrown.
public void onlyOneOf(java.lang.String... flags)
public void isMutuallyExclusive(java.lang.String... flags)
onlyOneOf
method.
public java.lang.String[] rawValues()
public java.util.Map values()
public void setUsage(java.lang.String str)
str
- Usage informationpublic void setDefaultUsage(java.lang.Object caller)
The name of the usage file is the same as the class name of the specified object (without the ending ".java") appended with "_usage.txt". Therefore the usage file for code residing in a.b.foo.java should be called foo_usage.txt and reside in the a/b directory.
caller
- the calling object or Class
Class
corresponding to that objectpublic void setDefaultUsage(java.lang.String pathToFile)
public void showError()
getRequired
with a non-existent flag name.
public static void main(java.lang.String[] args) throws java.lang.Exception
java.lang.Exception
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |