shell% myexecutable limits=1000 happy=True
would run "myexecutable" and set the internal parameter "limits" to a value
of 1000 and "happy" to True.
The Input class is instantiated by a constructor with a single Int argument which, when non-zero, switches on the filling of the keys "debug" and "help" from environment variables. These two keys always exist in an instance of Input. No argument to the Input constructor defaults to "debug" and "help" being set to zero.
The default existance of the help parameter allows the user to specify predefined modes for the "help" key. The argument "help=prompt" turns on prompting for parameter values not specified on the command-line. In such an instance, the optional String arguments to Input::create become important. The argument "help=keys" will print to standard output a list of all the parameters. Finally, "help=pane" prints to standard output a pane file usable as a graphic user interface within Khoros Cantata.
The default existance of the debug parameter allows the user to specify levels of debugging, where 0 implies none and higher integers means more. The usage would be as follows:
Input inp;
// this will execute the block only for values higher than 5
if(inp.debug(5))
{
// do debugging stuff here
}
Additional parameters must be created inside the main block (or deeper) of your application. The member function create() is overloaded to accept from one to six String arguments. All but the first are optional. However, should the user decide to call any of the get() functions which return a String, that String will be empty. In this case it is assumed that all values will be filled from the command line. Some examples:
main(Int argc, char *argv[])
{
Input inp;
// Create a parameter called "foo" which defaults to True.
inp.create("foo", "True");
// Create a parameter called "iterbound" which defaults to 2000 and
// has a help String used in cases of prompting.
inp.create("iterbound", "2000", "The upper boundary of the iterator");
// Create a normalising value with a range, type, and unit.
inp.create("dividend", "10000", The normalization factor of the chutspah",
"0-100000", "Double", "clean steps");
The parameters are "filled" from the command line arguments by the member
function ReadArguments(int argc, char**argv). If an argument is not defined
within the main block but specified at the command line, an exception is
thrown.
inp.readArguments(argc, argv);
Finally, the values of the various parameter's are utilized by calling the Input::getWhatever(key) member functions. They return either a String or are converted to the data type chosen by the "whatever" in the name of the function. The value associated with the passed key is returned.
// get a boolean
if(inp.getBool("foo")
// get an iteration boundary
for(Int i=0; i<inp.getInt("iterbound"); i++) {
// get a double
chutspah /= inp.getDouble("dividend");
}
Optional items include:
#include <aips/Inputs/Input.h>
main(Int argc, char *argv[])
{
// instantiate an Input. The integer argument of 1 to the ctor builds
// the system parameters "debug" and "help" and sets their values to the
// shell environment variables DEBUG and HELP.
Input inp(1);
// set the version to be automatically expanded by the RCS. This will
// print the version at run time.
inp.version("$ID:$");
// We will now create some parameters.
// Create a parameter with no default value i.e. it must be set by a
// command line argument.
inp.create("test");
// Create a parameter with a default value.
inp.create("file", "$AIPSROOT/data.txt");
// Create a parameter with a help String which will be displayed when in
// the prompted entry mode.
inp.create("ubound", "1000", "The number of iterations to clean.");
// Create a parameter with a type. This is utilized to create the correct
// labels on a Khoros pane. You could do type checking yourself, as well.
inp.create("baseline", "451", "The number of baselines.", "Int");
// Create a parameter with a range of acceptable values. Note: checking
// must be done by the user as this isn't coded in.
inp.create("gainstride", "0.5", "The factor by which the Clean strides.",
"Double", "0-1.0");
// Create a parameter with a unit String. Note: checking must be done
// by the user as this test isn't coded in.
String help("The velocity of the Earth in the direction of the object.");
inp.create("velocity", "2.89e+05", help, "Double", "0-3.0e+06", "m/s");
// Now we close parameter creation and get the values from the command line
// arguments.
inp.readArguments(argc, argv);
// Now we may utilize the values from the paramters we have created.
// Here we are getting a boolean from the parameter with the key "test".
if(inp.getBool("test") {
// Here we get a String from the parameter with the key "file".
Image myImage(inp.getString("file"));
// Here we set the boundary of the loop.
for(Int i=0;i<inp.getInt("ubound"), i++) {
// Here we set a value to the number of baselines.
Int baseline = inp.getInt("baseline");
// Here we set the gain stride.
Cleaner.gain(inp.getDouble("gainstride"));
// lets add a debugging block
if(inp.debug(5)) cout << "the chutspah is " << chutspah << endl;
}
}
Destructor.
Create a new parameter, either from scratch or looking it
up from an internal list of templates.
The function also checks whether parameters can still be created,
and whether key is unique for the program.
The value, help and remaining arguments are all optional.
Disable the creation of parameters. Highly recommended, but not required. readArguments calls it when filling the values from argv[].
fill the parameter list from argc, argv command line args
Get the double value of the parameter (or 0.0 if unknown key). If the program is in prompt mode, ask the user for the value.
Get the Block
Get the int value of the parameter (or 0 if unknown key).
If the program is in prompt mode, ask the user for the value.
Get the Block
Get the String value of the parameter (or "" if unknown key).
If the program is in prompt mode, ask the user for the value.
Get the boolean value of the parameter (or FALSE if unknown key).
If the program is in prompt mode, ask the user for the value.
Get the total number of parameters of this program
See if the current debug level is thresholded
Set a new value for an existing named parameter
Returns FALSE if key is an unknown parameter name.
The single argument is of the form `key=value', where key is a valid
parameter name.
Set a new value for an existing named parameter
Returns FALSE if key is an unknown parameter name.
Set version string for announcements
Announce program and version.
Turn a string in the form "5,7,9-11,13,2-4" into a Vector
Prompt the user for a value for the parameter.
If he gives a non-empty answer, set that value.
Bind an environment variable to a parameter
The actual creation of a new (system/program) parameter
output to stdout a Khoros Cantata pane.
output to stdout a listing of all "key=value" pairs.
Int getInt (const String& key)
Block<Int> getIntArray (const String& key)
String getString (const String& key)
Bool getBool (const String& key)
Int count() const
Bool debug (Int l) const
Bool put (const String& keyval)
Bool put (const String& key, const String& value)
void version (const String&)
void announce()
static Vector<Bool> makeMaskFromRanges(const String& ranges, uInt length, Bool oneRelative=False)
Int getParam (const String& key) const
Get the index of the named parameter (0 if unknown key).
Anywhere from 1.. if a key is found.
void prompt (Param& parameter) const
void envCreate (const Char *env, const String& key, const String& def)
void createPar (Int, const String&, const String&, const String&, const String&, const String&, const String&)
void pane()
void keys()