org.knowceans.util
Class Arguments

java.lang.Object
  org.knowceans.util.Arguments

public class Arguments
extends java.lang.Object

Arguments is a convenience class that reads command line arguments for main and validates them against a given format. The general grammar of a commandline is:

 
  commandline ::= command " " options arguments
  
 

Here the options and arguments follow the grammar:

 
  options   ::= ( option " " )+
  option    ::= "-" name (" " value)?
  name      ::= <LITERAL>  
  arguments ::= ( argument )+ 
  argument  ::= value
  value     ::= <LITERAL> | """( <LITERAL> | " " )+ """
  
 

with some value. Values can be restricted to specific formats, which is done using a format string. Known types are int, float, long, double, boolean, String, File and URL. String and File values can contain spaces if put within quotes.

TODO: resolve problem with command line monitor getCallString()

Author:

heinrich

Constructor Summary

Arguments(java.lang.String optformat, java.lang.String argtypes)
Initialise the arguments parser with a format string and an argument type specification.

Arguments(java.lang.String optformat, java.lang.String argtypes, java.lang.String helptext)
same as 2-argument constructor, but sets a help text.

Method Summary

void	close() This method must be called if output redirection is used.
void	debug(boolean b)
java.lang.Object	getArgument(int i) Returns the argument with index i and null if i is compliant with the format but not specified at commandline.
java.lang.Object	getArgument(int i, java.lang.Object defaultValue) Same as getArgument, but returns a default value if optional argument is not set.
java.util.Vector<java.lang.Object>	getArguments() get the vector of all arguments.
java.lang.String	getCallString(boolean format) The full call string of the program, including the classpath and working directory.
java.lang.Object	getOption(java.lang.String string) returns the named option value.
java.lang.Object	getOption(java.lang.String string, java.lang.Object defaultValue) Same as getOption, but allows default value (whose type is NOT checked).
java.util.HashMap<java.lang.String,java.lang.Object>	getOptions() get the map of options.
void	help(java.lang.String string)
static void	main(java.lang.String[] args)
void	parse(java.lang.String[] args) Parses the command line arguments string whose values can be found with the getOption and getArgument methods afterwards.
void	redirect(boolean b) Enable / disable redirection of pipe streams (default = disabled)
void	spacePad(java.lang.StringBuffer b, int length)
void	tee(boolean b) Enable / disable output duplication (default = enabled).
java.lang.String	toString() describe the current arguments set
java.lang.String	type(char c)
void	variable(boolean b) Enable / disable variable replacement (default = disabled).

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Arguments

public Arguments(java.lang.String optformat,
                 java.lang.String argtypes)

Initialise the arguments parser with a format string and an argument type specification. For the options and arguments, the formats are defined by this constructor.

The format string for the options is composed of the following grammar:

 
  foptions   ::= ( option )*
  foption    ::= name ( "|" name )? "=" fotype " "? ( "{" fhelp "}" )?
  fname      ::= <LITERAL>
  fotype     ::= ( i | l | f | d | b | u | p | s | 0 )
  fhelp      ::= <LITERAL>
  
 

The literals of fotype correspond to the types int, float, long, double, boolean, java.net.URL, java.io.File (p), java.lang.String, and void (0) for unparametrised options

The format string for the arguments is composed of the following grammar:

 
  farguments    ::= frequiredargs "|" foptionalargs
  frequiredargs ::= ( fatype " "? ( "{" fhelp "}" )? )+
  foptionalargs ::= ( fatype " "? ( "{" fhelp "}" )? )+)+
  fatype        ::= ( i | l | f | d | b | u | p | s )
  fhelp      ::= <LITERAL>
  
 

The help strings can include line breaks "\n".

Parameters:

optformat - format string for options

argtypes - format string for arguments

Arguments

public Arguments(java.lang.String optformat,
                 java.lang.String argtypes,
                 java.lang.String helptext)

same as 2-argument constructor, but sets a help text.

Parameters:

optformat -

argtypes -

helptext -

Method Detail

main

public static void main(java.lang.String[] args)

getOptions

public java.util.HashMap<java.lang.String,java.lang.Object> getOptions()

get the map of options.

Returns:

getOption

public java.lang.Object getOption(java.lang.String string)
                           throws java.lang.IllegalArgumentException

returns the named option value. If it has no parameter, Boolean.TRUE is returned if given, otherwise Boolean.FALSE.

Parameters:

string - key for the option parameter.

Returns:

value of option parameter (that can be casted to the specific type) or null if not given at command line or not in format.

Throws:

java.lang.IllegalArgumentException

getOption

public java.lang.Object getOption(java.lang.String string,
                                  java.lang.Object defaultValue)
                           throws java.lang.IllegalArgumentException

Same as getOption, but allows default value (whose type is NOT checked).

Parameters:

string -

defaultValue -

Returns:

Throws:

java.lang.IllegalArgumentException

getArguments

public java.util.Vector<java.lang.Object> getArguments()

get the vector of all arguments.

Returns:

getArgument

public java.lang.Object getArgument(int i)
                             throws java.lang.IllegalArgumentException

Returns the argument with index i and null if i is compliant with the format but not specified at commandline. Arguments start at the index 1, index 0 returns a the full name of the main class.

Parameters:

i -

Returns:

Throws:

java.lang.IllegalArgumentException

getCallString

public java.lang.String getCallString(boolean format)

The full call string of the program, including the classpath and working directory. TODO: parameterless options are printed with boolean value...

Parameters:

format - true to format lines.

Returns:

getArgument

public java.lang.Object getArgument(int i,
                                    java.lang.Object defaultValue)

Same as getArgument, but returns a default value if optional argument is not set. The type of the default is NOT checked.

Parameters:

i -

defaultValue -

Returns:

parse

public void parse(java.lang.String[] args)
           throws java.lang.IllegalArgumentException

Parses the command line arguments string whose values can be found with the getOption and getArgument methods afterwards. Further, if option -? is not specified in the format string, the help string (accessible via toString()) is output to stdout and System.exit(0) called. The same works for -stdout and a file where the output is sent to, -stderr, -stdouterr, and -stdin work accordingly. Stream redirection must be explicitly enabled by calling redirect(true) and, at the end of the program, to call the close() method. By default, streams are duplicated to stdout / stderr to allow monitoring, disable stream duplication by calling tee(false).

Another important possibility is the option -$, which allows to set a variable that can be used afterwards in the option and argument values by using $@. Enable this using the variable(true);

Parameters:

args - the argument string, typically directly that of a main method.

Throws:

java.lang.IllegalArgumentException - if the commandline arguments do not match the given format.

toString

public java.lang.String toString()

describe the current arguments set

Overrides:

toString in class java.lang.Object

spacePad

public void spacePad(java.lang.StringBuffer b,
                     int length)

type

public java.lang.String type(char c)

debug

public void debug(boolean b)

Parameters:

b -

help

public void help(java.lang.String string)

Parameters:

string -

close

public void close()

This method must be called if output redirection is used.

redirect

public void redirect(boolean b)

Enable / disable redirection of pipe streams (default = disabled)

Parameters:

b -

variable

public void variable(boolean b)

Enable / disable variable replacement (default = disabled).

Parameters:

b -

tee

public void tee(boolean b)

Enable / disable output duplication (default = enabled).

Parameters:

b -