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