casacore
Input.h
Go to the documentation of this file.
1//# Input.h: A simple command-line argument method for applications.
2//# Copyright (C) 1993,1994,1995,1999,2000,2001
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//# $Id$
27
28#ifndef CASA_INPUT_H
29#define CASA_INPUT_H
30
31
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Arrays/ArrayFwd.h>
34#include <casacore/casa/Inputs/Param.h>
35#include <vector>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39// <summary>
40// Input.h: A simple command-line argument method for applications.
41// </summary>
42
43// <use visibility=export>
44
45// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tInput.cc" demos="">
46//</reviewed>
47
48// <prerequisite>
49// <li> none noted
50// </prerequisite>
51//
52// <etymology>
53// The Input class name is a reflection of it's role as the early command
54// line user interface for Casacore applications. This class provides "inputs"
55// in the form "key=value" or "-key value."
56// </etymology>
57//
58// <synopsis>
59// The Input class is a holder of parameters, either automatically assigned
60// values or altered at the execution of the program which utilizes them. The
61// parameters are associations of String "keys" to "values". The parameters
62// may be used as internal values during the program's run. The shell command
63// <srcblock>
64// shell% myexecutable limits=1000 happy=True
65// </srcblock>
66// would run "myexecutable" and set the internal parameter "limits" to a value
67// of 1000 and "happy" to True.
68//
69// The Input class is instantiated by a constructor with a single Int argument
70// which, when non-zero, switches on the filling of the keys "debug" and
71// "help" from environment variables. These two keys always exist in an
72// instance of Input. No argument to the Input constructor defaults to "debug"
73// and "help" being set to zero.
74//
75// The default existance of the help parameter allows the user to specify
76// predefined modes for the "help" key. The argument "help=prompt" turns
77// on prompting for parameter values not specified on the command-line. In
78// such an instance, the optional String arguments to Input::create become
79// important. The argument "help=keys" will print to standard output a list
80// of all the parameters.
81//
82// The default existance of the debug parameter allows the user to specify
83// levels of debugging, where 0 implies none and higher integers means more.
84// The usage would be as follows:
85// <srcblock>
86// Input inp;
87// // this will execute the block only for values higher than 5
88// if(inp.debug(5))
89// {
90// // do debugging stuff here
91// }
92// </srcblock>
93//
94// Additional parameters must be created inside the main block (or deeper)
95// of your application. The member function create() is overloaded to accept
96// from one to six String arguments. All but the first are optional. However,
97// should the user decide to call any of the get() functions which return a
98// String, that String will be empty. In this case it is assumed that all
99// values will be filled from the command line.
100// Some examples:
101// <srcblock>
102// int main(int argc,const char* argv[])
103// {
104// Input inp;
105// // Create a parameter called "foo" which defaults to True.
106// inp.create("foo", "True");
107// // Create a parameter called "iterbound" which defaults to 2000 and
108// // has a help String used in cases of prompting.
109// inp.create("iterbound", "2000", "The upper boundary of the iterator");
110// // Create a normalising value with a range, type, and unit.
111// inp.create("dividend", "10000", The normalization factor of the chutspah",
112// "0-100000", "Double", "clean steps");
113// </srcblock>
114// The parameters are "filled" from the command line arguments by the member
115// function ReadArguments(int argc, const char* argv[]). If an argument is not defined
116// within the main block but specified at the command line, an exception is
117// thrown.
118// <srcblock>
119// inp.readArguments(argc, argv);
120// </srcblock>
121//
122// Finally, the values of the various parameter's are utilized by calling the
123// Input::getWhatever(key) member functions. They return either a String or
124// are converted to the data type chosen by the "whatever" in the name of the
125// function. The value associated with the passed key is returned.
126// <srcblock>
127// // get a boolean
128// if(inp.getBool("foo")
129// // get an iteration boundary
130// for(Int i=0; i<inp.getInt("iterbound"); i++) {
131// // get a double
132// chutspah /= inp.getDouble("dividend");
133// }
134// </srcblock>
135//
136// Optional items include:
137// <ol> <li> specifying a version <src> inp.version("$ID:");</src>
138// will print at run time the version of the program being run.
139// <li> run time checking of ranges
140// <src> inp.makeMaskFromRanges(const String &ranges, uInt length,
141// Bool oneRelative=False); </src>
142// </ol>
143// </synopsis>
144//
145// <example>
146// <srcblock>
147// #include <casacore/casa/Inputs/Input.h>
148// int main(int argc, const char* argv[])
149// {
150// // instantiate an Input. The integer argument of 1 to the ctor builds
151// // the system parameters "debug" and "help" and sets their values to the
152// // shell environment variables DEBUG and HELP.
153// Input inp(1);
154// // set the version to be automatically expanded by the RCS. This will
155// // print the version at run time.
156// inp.version("$ID:$");
157// // We will now create some parameters.
158// // Create a parameter with no default value i.e. it must be set by a
159// // command line argument.
160// inp.create("test");
161// // Create a parameter with a default value.
162// inp.create("file", "$AIPSROOT/data.txt");
163// // Create a parameter with a help String which will be displayed when in
164// // the prompted entry mode.
165// inp.create("ubound", "1000", "The number of iterations to clean.");
166// // Create a parameter with a range of acceptable values. Note: checking
167// // must be done by the user as this isn't coded in.
168// inp.create("gainstride", "0.5", "The factor by which the Clean strides.",
169// "Double", "0-1.0");
170// // Create a parameter with a unit String. Note: checking must be done
171// // by the user as this test isn't coded in.
172// String help("The velocity of the Earth in the direction of the object.");
173// inp.create("velocity", "2.89e+05", help, "Double", "0-3.0e+06", "m/s");
174// // Now we close parameter creation and get the values from the command line
175// // arguments.
176// inp.readArguments(argc, argv);
177// // Now we may utilize the values from the paramters we have created.
178// // Here we are getting a boolean from the parameter with the key "test".
179// if(inp.getBool("test") {
180// // Here we get a String from the parameter with the key "file".
181// Image myImage(inp.getString("file"));
182// // Here we set the boundary of the loop.
183// for(Int i=0;i<inp.getInt("ubound"), i++) {
184// // Here we set a value to the number of baselines.
185// Int baseline = inp.getInt("baseline");
186// // Here we set the gain stride.
187// Cleaner.gain(inp.getDouble("gainstride"));
188// // lets add a debugging block
189// if(inp.debug(5)) cout << "the chutspah is " << chutspah << endl;
190// }
191// }
192// </srcblock>
193// </example>
194//
195// <motivation>
196// In the earliest days of the old AIPS++ project, the desire to start coding
197// right away led to the need for a user interface. The preexistant C language
198// method of argc/argv was enclosed in an object for easier use.
199// </motivation>
200
201
202class Input {
203public:
204
205 // The default constructor enables the creation of parameters.
206 // If the optional Int argument is non-zero, the parameters "help" and
207 // "debug" are created from their shell environment values.
208 // This puts the program in no-prompt mode unless environment variable HELP
209 // is defined with value "prompt". The output debug level is set according
210 // to the value of the environment variable DEBUG.
211 Input (Int createEnv=0);
212
213 // Destructor.
215
216 // Create a new parameter, either from scratch or looking it
217 // up from an internal list of templates.
218 // The function also checks whether parameters can still be created,
219 // and whether key is unique for the program.
220 // The value, help and remaining arguments are all optional.
221 // <note> The multiple definitions are to allow default values</note>
222 // <group>
223 void create (const String& key);
224 void create (const String& key, const String& value);
225 void create (const String& key, const String& value, const String& help);
226 void create (const String& key, const String& value, const String& help,
227 const String& type);
228 void create (const String& key, const String& value, const String& help,
229 const String& type, const String& range);
230 void create (const String& key, const String& value, const String& help,
231 const String& type, const String& range, const String& unit);
232 // </group>
233
234 // Disable the creation of parameters. Highly recommended, but
235 // not required. readArguments calls it when filling the values from argv[].
236 void close();
237
238 // fill the parameter list from argc, argv command line args
239 void readArguments (int argc, char const* const* argv);
240
241 // Get the double value of the parameter (or 0.0 if unknown key).
242 // If the program is in prompt mode, ask the user for the value.
243 Double getDouble (const String& key);
244
245 // Get the Block<double> value of the parameter (or default Block if unknown
246 // key).
247 // If the program is in prompt mode, ask the user for the value.
249
250 // Get the int value of the parameter (or 0 if unknown key).
251 // If the program is in prompt mode, ask the user for the value.
252 Int getInt (const String& key);
253
254 // Get the Block<int> value of parameter (or default Block if unknown key)
255 // If the program is in prompt mode, ask the user for the value.
257
258 // Get the String value of the parameter (or "" if unknown key).
259 // If the program is in prompt mode, ask the user for the value.
260 String getString (const String& key);
261
262 // Get the boolean value of the parameter (or FALSE if unknown key).
263 // If the program is in prompt mode, ask the user for the value.
264 Bool getBool (const String& key);
265
266 // Get the total number of parameters of this program
267 Int count() const;
268
269 // See if the current debug level is thresholded
270 Bool debug (Int l) const
271 { return (debug_level >= l) ? True : False; }
272
273 // Set a new value for an existing named parameter
274 // Returns FALSE if key is an unknown parameter name.
275 // <group>
276 Bool put (const String& key, const String& value);
277
278 // The single argument is of the form `key=value', where key is a valid
279 // parameter name.
280 Bool put (const String& keyval);
281 // </group>
282
283 // Set version string for announcements
284 void version (const String&);
285
286 // Announce program and version.
287 void announce();
288
289 // Turn a string in the form "5,7,9-11,13,2-4" into a Vector<Bool>, where
290 // each specified position or range, is set to True and every other position
291 // is set to False. While the returned vector always has a zero origin, if
292 // oneRelative is True, all the numbers in the supplied string are
293 // decremented before use. Spaces in ranges are ignored, but otherwise
294 // ill-formed strings, or numbers that would fill in beyond the length
295 // of the Vector<Bool> results in an exception being thrown.
297 Bool oneRelative=False);
298
299
300private:
301 // Get the index of the named parameter (-1 if unknown key).
302 // Anywhere from 0.. if a key is found.
303 Int getParam (const String& key) const;
304
305 // Prompt the user for a value for the parameter.
306 // If he gives a non-empty answer, set that value.
307 void prompt (Param& parameter) const;
308
309 // Bind an environment variable to a parameter
310 void envCreate (const Char *env, const String& key, const String& def);
311
312 // The actual creation of a new (system/program) parameter
313 void createPar (Int, const String&, const String&, const String&,
314 const String&, const String&, const String&);
315
316 // output to stdout a listing of all "key=value" pairs.
317 void keys();
318
319
320 // container of parameters
321 std::vector<Param> parList_p;
322
323 // version id
325
326 // parameter creation allowed?
328
329 // ask user for parameter value?
331
332 // threshold value for debug output
334
335 // "prompt" or "keys" indicates the various types of help.
337
338 // count of program parameters
340};
341
342
343} //# NAMESPACE CASACORE - END
344
345#endif
346
347
void create(const String &key, const String &value)
Int p_count
count of program parameters
Definition: Input.h:339
void announce()
Announce program and version.
void envCreate(const Char *env, const String &key, const String &def)
Bind an environment variable to a parameter.
Bool debug(Int l) const
See if the current debug level is thresholded.
Definition: Input.h:270
void create(const String &key, const String &value, const String &help, const String &type)
String getString(const String &key)
Get the String value of the parameter (or "" if unknown key).
Bool do_prompt
ask user for parameter value?
Definition: Input.h:330
Int getInt(const String &key)
Get the int value of the parameter (or 0 if unknown key).
void version(const String &)
Set version string for announcements.
void prompt(Param &parameter) const
Prompt the user for a value for the parameter.
Block< Double > getDoubleArray(const String &key)
Get the Block<double> value of the parameter (or default Block if unknown key).
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 ran...
void close()
Disable the creation of parameters.
String version_id
version id
Definition: Input.h:324
void createPar(Int, const String &, const String &, const String &, const String &, const String &, const String &)
The actual creation of a new (system/program) parameter.
Bool is_closed
parameter creation allowed?
Definition: Input.h:327
Double getDouble(const String &key)
Get the double value of the parameter (or 0.0 if unknown key).
void readArguments(int argc, char const *const *argv)
fill the parameter list from argc, argv command line args
~Input()
Destructor.
std::vector< Param > parList_p
container of parameters
Definition: Input.h:321
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 m...
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, const String &range)
Bool put(const String &keyval)
The single argument is of the form ‘key=value’, where key is a valid parameter name.
Int count() const
Get the total number of parameters of this program.
Input(Int createEnv=0)
The default constructor enables the creation of parameters.
void create(const String &key, const String &value, const String &help, const String &type, const String &range, const String &unit)
Bool getBool(const String &key)
Get the boolean value of the parameter (or FALSE if unknown key).
void create(const String &key)
Create a new parameter, either from scratch or looking it up from an internal list of templates.
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.
Int getParam(const String &key) const
Get the index of the named parameter (-1 if unknown key).
void keys()
output to stdout a listing of all "key=value" pairs.
Int debug_level
threshold value for debug output
Definition: Input.h:333
String help_mode
"prompt" or "keys" indicates the various types of help.
Definition: Input.h:336
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
LatticeExprNode length(const LatticeExprNode &expr, const LatticeExprNode &axis)
2-argument function to get the length of an axis.
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55
char Char
Definition: aipstype.h:46