casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
35 #include <vector>
36 
37 namespace 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 
202 class Input {
203 public:
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.
214  ~Input();
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.
248  Block<Double> getDoubleArray (const String& key);
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.
256  Block<Int> getIntArray (const String& key);
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.
296  static Vector<Bool> makeMaskFromRanges(const String& ranges, uInt length,
297  Bool oneRelative=False);
298 
299 
300 private:
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 
Bool getBool(const String &key)
Get the boolean value of the parameter (or FALSE if unknown key).
std::vector< Param > parList_p
container of parameters
Definition: Input.h:321
int Int
Definition: aipstype.h:50
Bool do_prompt
ask user for parameter value?
Definition: Input.h:330
Bool debug(Int l) const
See if the current debug level is thresholded.
Definition: Input.h:270
String version_id
version id
Definition: Input.h:324
A simple keyword/value pair with internal help Strings.
Definition: Param.h:113
char Char
Definition: aipstype.h:46
void readArguments(int argc, char const *const *argv)
fill the parameter list from argc, argv command line args
void create(const String &key)
Create a new parameter, either from scratch or looking it up from an internal list of templates...
Block< Double > getDoubleArray(const String &key)
Get the Block&lt;double&gt; 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:55
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:339
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&lt;int&gt; value of parameter (or default Block if unknown key) If the program is in prompt m...
Int getParam(const String &key) const
Get the index of the named parameter (-1 if unknown key).
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:42
Int debug_level
threshold value for debug output
Definition: Input.h:333
static Vector< Bool > makeMaskFromRanges(const String &ranges, uInt length, Bool oneRelative=False)
Turn a string in the form &quot;5,7,9-11,13,2-4&quot; into a Vector&lt;Bool&gt;, where each specified position or ran...
void keys()
output to stdout a listing of all &quot;key=value&quot; 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:44
String getString(const String &key)
Get the String value of the parameter (or &quot;&quot; if unknown key).
~Input()
Destructor.
Input.h: A simple command-line argument method for applications.
Definition: Input.h:202
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:225
Bool is_closed
parameter creation allowed?
Definition: Input.h:327
void version(const String &)
Set version string for announcements.
Input(Int createEnv=0)
The default constructor enables the creation of parameters.
void prompt(Param &parameter) const
Prompt the user for a value for the parameter.
String help_mode
&quot;prompt&quot; or &quot;keys&quot; indicates the various types of help.
Definition: Input.h:336
const Bool True
Definition: aipstype.h:43
Int count() const
Get the total number of parameters of this program.
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
unsigned int uInt
Definition: aipstype.h:51