Input.h: A simple command-line argument method for applications. More...

#include <Input.h>

Public Member Functions
	Input (Int createEnv=0)
	The default constructor enables the creation of parameters.
	~Input ()
	Destructor.
void	create (const String &key)
	Create a new parameter, either from scratch or looking it up from an internal list of templates.
void	create (const String &key, const String &value)
void	create (const String &key, const String &value, const String &help)
void	create (const String &key, const String &value, const String &help, const String &type)
void	create (const String &key, const String &value, const String &help, const String &type, const String &range)
void	create (const String &key, const String &value, const String &help, const String &type, const String &range, const String &unit)
void	close ()
	Disable the creation of parameters.
void	readArguments (int argc, char const const argv)
	fill the parameter list from argc, argv command line args
Double	getDouble (const String &key)
	Get the double value of the parameter (or 0.0 if unknown key).
Block< Double >	getDoubleArray (const String &key)
	Get the Block<double> value of the parameter (or default Block if unknown key).
Int	getInt (const String &key)
	Get the int value of the parameter (or 0 if unknown key).
Block< Int >	getIntArray (const String &key)
	Get the Block<int> value of parameter (or default Block if unknown key) If the program is in prompt mode, ask the user for the value.
String	getString (const String &key)
	Get the String value of the parameter (or "" if unknown key).
Bool	getBool (const String &key)
	Get the boolean value of the parameter (or FALSE if unknown key).
Int	count () const
	Get the total number of parameters of this program.
Bool	debug (Int l) const
	See if the current debug level is thresholded.
Bool	put (const String &key, const String &value)
	Set a new value for an existing named parameter Returns FALSE if key is an unknown parameter name.
Bool	put (const String &keyval)
	The single argument is of the form `key=value', where key is a valid parameter name.
void	version (const String &)
	Set version string for announcements.
void	announce ()
	Announce program and version.
Static Public Member Functions
static Vector< Bool >	makeMaskFromRanges (const String &ranges, uInt length, Bool oneRelative=False)
	Turn a string in the form "5,7,9-11,13,2-4" into a Vector<Bool>, where each specified position or range, is set to True and every other position is set to False.
Private Member Functions
Int	getParam (const String &key) const
	Get the index of the named parameter (0 if unknown key).
void	prompt (Param &parameter) const
	Prompt the user for a value for the parameter.
void	envCreate (const Char *env, const String &key, const String &def)
	Bind an environment variable to a parameter.
void	createPar (Int, const String &, const String &, const String &, const String &, const String &, const String &)
	The actual creation of a new (system/program) parameter.
void	pane ()
	output to stdout a Khoros Cantata pane.
void	keys ()
	output to stdout a listing of all "key=value" pairs.
Private Attributes
List< Param >	parList_p
	linked list container of parameters
String	version_id
	version id
Bool	is_closed
	parameter creation allowed?
Bool	do_prompt
	ask user for parameter value?
Int	debug_level
	threshold value for debug output
String	help_mode
	"prompt", "keys", or "pane" indicates the various types of help.
Int	p_count
	count of program parameters

Detailed Description

Input.h: A simple command-line argument method for applications.

Intended use:

Public interface

Review Status

Reviewed By:: UNKNOWN
Date Reviewed:: before2004/08/25
Test programs:: tInput

Prerequisite

none noted

Etymology

The Input class name is a reflection of it's role as the early command line user interface for AIPS++ applications. This class provides "inputs" in the form "key=value" or "-key value."

Synopsis

The Input class is a holder of parameters, either automatically assigned values or altered at the execution of the program which utilizes them. The parameters are associations of String "keys" to "values". The parameters may be used as internal values during the program's run. The shell command

    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:

    int main(int argc,const 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, const 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:

specifying a version inp.version("$ID:"); will print at run time the version of the program being run.
run time checking of ranges inp.makeMaskFromRanges(const String &ranges, uInt length, Bool oneRelative=False);

Example

    #include <casa/Inputs/Input.h>
    int main(int argc, const 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;
      }
    }

Motivation

In the earliest days of the AIPS++ project, the desire to start coding right away led to the need for a user interface. The preexistant C language method of argc/argv was enclosed in an object for easier use. This also provided a means to output a pane file. Pane files are used by the Cantata desktop within the Khoros system to build quick graphic user interfaces. The AIPS++ code has moved on to greater heights and left the Input class mostly unchanged.

To Do

major cleanup needed - this is the oldest code in AIPS++.
replace List<Param> with keywords

Definition at line 216 of file Input.h.

Constructor & Destructor Documentation

casa::Input::Input ( Int createEnv = 0 )

The default constructor enables the creation of parameters.

If the optional Int argument is non-zero, the parameters "help" and "debug" are created from their shell environment values. This puts the program in no-prompt mode unless environment variable HELP is defined with value "prompt". The output debug level is set according to the value of the environment variable DEBUG.

casa::Input::~Input ( )

Destructor.

Member Function Documentation

void casa::Input::announce ( )

Announce program and version.

void casa::Input::close ( )

Disable the creation of parameters.

Highly recommended, but not required. readArguments calls it when filling the values from argv[].

Int casa::Input::count ( ) const

Get the total number of parameters of this program.

void casa::Input::create ( const String & key )

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.
Note: The multiple definitions are to allow default values

void casa::Input::create	(	const String &	key,
		const String &	value
	)

void casa::Input::create	(	const String &	key,
		const String &	value,
		const String &	help
	)

void casa::Input::create	(	const String &	key,
		const String &	value,
		const String &	help,
		const String &	type
	)

void casa::Input::create	(	const String &	key,
		const String &	value,
		const String &	help,
		const String &	type,
		const String &	range
	)

void casa::Input::create	(	const String &	key,
		const String &	value,
		const String &	help,
		const String &	type,
		const String &	range,
		const String &	unit
	)

void casa::Input::createPar	(	Int	,
		const String &	,
		const String &	,
		const String &	,
		const String &	,
		const String &	,
		const String &
	)		`[private]`

The actual creation of a new (system/program) parameter.

Bool casa::Input::debug ( Int l ) const [inline]

See if the current debug level is thresholded.

Definition at line 284 of file Input.h.

References debug_level, casa::False, and casa::True.

void casa::Input::envCreate	(	const Char *	env,
		const String &	key,
		const String &	def
	)		`[private]`

Bind an environment variable to a parameter.

Bool casa::Input::getBool ( const String & key )

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.

Double casa::Input::getDouble ( const String & key )

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.

Block<Double> casa::Input::getDoubleArray ( const String & key )

Get the Block<double> value of the parameter (or default Block if unknown key).

If the program is in prompt mode, ask the user for the value.

Int casa::Input::getInt ( const String & key )

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.

Block<Int> casa::Input::getIntArray ( const String & key )

Get the Block<int> value of parameter (or default Block if unknown key) If the program is in prompt mode, ask the user for the value.

Int casa::Input::getParam ( const String & key ) const [private]

Get the index of the named parameter (0 if unknown key).

Anywhere from 1.. if a key is found.

String casa::Input::getString ( const String & key )

Get the String value of the parameter (or "" if unknown key).

If the program is in prompt mode, ask the user for the value.

void casa::Input::keys ( ) [private]

output to stdout a listing of all "key=value" pairs.

static Vector<Bool> casa::Input::makeMaskFromRanges	(	const String &	ranges,
		uInt	length,
		Bool	oneRelative = `False`
	)		`[static]`

Turn a string in the form "5,7,9-11,13,2-4" into a Vector<Bool>, where each specified position or range, is set to True and every other position is set to False.

While the returned vector always has a zero origin, if oneRelative is True, all the numbers in the supplied string are decremented before use. Spaces in ranges are ignored, but otherwise ill-formed strings, or numbers that would fill in beyond the length of the Vector<Bool> results in an exception being thrown.

void casa::Input::pane ( ) [private]

output to stdout a Khoros Cantata pane.

void casa::Input::prompt ( Param & parameter ) const [private]

Prompt the user for a value for the parameter.

If he gives a non-empty answer, set that value.

Bool casa::Input::put	(	const String &	key,
		const String &	value
	)

Set a new value for an existing named parameter Returns FALSE if key is an unknown parameter name.

Bool casa::Input::put ( const String & keyval )

The single argument is of the form `key=value', where key is a valid parameter name.

void casa::Input::readArguments	(	int	argc,
		char const const	argv
	)

fill the parameter list from argc, argv command line args

void casa::Input::version ( const String & )

Set version string for announcements.

Member Data Documentation

Int casa::Input::debug_level [private]

threshold value for debug output

Definition at line 350 of file Input.h.

Referenced by debug().

Bool casa::Input::do_prompt [private]

ask user for parameter value?

Definition at line 347 of file Input.h.

String casa::Input::help_mode [private]

"prompt", "keys", or "pane" indicates the various types of help.

Definition at line 353 of file Input.h.

Bool casa::Input::is_closed [private]

parameter creation allowed?

Definition at line 344 of file Input.h.

Int casa::Input::p_count [private]

count of program parameters

Definition at line 356 of file Input.h.

List<Param> casa::Input::parList_p [private]

linked list container of parameters

Definition at line 338 of file Input.h.

String casa::Input::version_id [private]

version id

Definition at line 341 of file Input.h.

The documentation for this class was generated from the following file:

casacore/casa/Inputs/Input.h

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Motivation

To Do

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation