casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Inputs.h
Go to the documentation of this file.
1 //# Inputs.h: a module for simple command line user interface classes
2 //# Copyright (C) 1994,1995,1996,1999,2000
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_INPUTS_H
29 #define CASA_INPUTS_H
30 
31 #include <casacore/casa/aips.h>
32 
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 // <module>
39 //
40 // <summary>
41 // A module for simple command line user interface classes
42 // </summary>
43 
44 // <prerequisite>
45 // <li> String
46 // <li> The C language int main(int argc, const char* argv[]) convention.
47 // </prerequisite>
48 
49 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" demos="">
50 //</reviewed>
51 
52 // <etymology>
53 // The Inputs module name reflects the Casacore convention of pluralizing
54 // the name of the major class it contains.
55 // The Input class name is a reflection of it's role as the early command
56 // line user interface for Casacore applications. This class provides "inputs"
57 // in the form "key=value" or "-key value."
58 //</etymology>
59 //
60 // <synopsis>
61 
62 // During the old AIPS++ prototyping stage a basic command line user
63 // interface was developed. This attempt at easing the trouble of passing
64 // information to an executable program resulted in a set of C++ classes
65 // called Param and Input. The programmer may simply include the Input
66 // class into their code and have immediate Command Line User Interface
67 // (CLUI) capabilities. The programmer's Casacore application is run from
68 // the unix level prompt by invoking its name and listing linearly on the
69 // same command line the "keyword=values" or "-keyword values" associated
70 // with proper execution. The Input and Param classes will successfully
71 // parse the command line into the executable program and check for
72 // appropriateness.
73 
74 // The CLUI capabilities are further extended to a Graphical User
75 // Interface through the use of the Khoros Cantata environment. The user
76 // starts up Cantata from the unix prompt and, by utilizing a series of
77 // pull down windows, invisibly creates an X-based window for visual
78 // display of all parameters associated with the Casacore application's
79 // need for external input.
80 
81 // The basic command line user interface is an ordered series of
82 // "keyword=value" pairs, which we call parameters. The names parameter
83 // and keyword may correctly be used to refer to each other.
84 //
85 // The class Param (see Param.h) implements one single such parameter.
86 // Values may be Int, Block<Int>, double, Block<double>, Bool, or
87 // Strings. In addition to a name and a value, a Param parameter has a
88 // variety of other attributes, such as a one-line help string (useful
89 // when being prompted for input or with hypertext identifiers, etc...),
90 // a type, a range and optional units. All of these attributes are
91 // character strings; parsing and error checking is done at a different
92 // (hidden) level. The programmer, however, will never interact with a
93 // parameter through it's Param class interface. Interaction is done
94 // with the class Input, which is a container of Param's, with a variety
95 // of user interface attributes (help-level, debug-level, etc...).
96 //
97 // Although the programmer must supply the user interface with a number
98 // of predefined program parameters, the user interface itself will
99 // create a small number of system parameters (help=, debug=). The
100 // purpose of these is to tell the task how to communicate with the user
101 // and it's environment, and give the user control over these items. For
102 // example, the user may want to see (debug) messages above a certain
103 // threshold level. The programmer simply adds debug levels to their
104 // code and allows the user to specify how deeply they wish the debugging
105 // to progress.
106 //
107 // For example, a interactive UNIX shell session may look like:
108 //
109 //<srcblock>
110 // 1% MyProgram key1=val1 key3=val3
111 // 2% MyProgram key1=val1 key2=val3 debug=5
112 // 3% MyProgram help=prompt
113 // 4% MyProgram help=pane > prog.pane
114 //</srcblock>
115 //
116 // In command 1% the user has set several parameters for the program
117 // MyProgram to applicable values. The 2% command line invokes the
118 // executable and sets the level of displayed debugging to the programmer
119 // specified 5th level. Command 3%: the user is prompted, and parameter
120 // default values are restored. Command 4% gives an example of the
121 // self-describing mode of programs, where a pane description file for
122 // Khoros has been constructed. The latter is the first step toward
123 // building a Khoros Graphic User Interface.
124 //
125 // The Input class is a means for building a linked list of parameters
126 // and gaining access to them once created. Input takes care of
127 // system/environment variables and assigns their values within the
128 // programmer's code. The linked list of parameters is limited only by
129 // the number of names the programmer can dream up. The programmer need
130 // not think hard on the order of definition of parameters in Input. The
131 // list of key=values given on the command line by the user need not be
132 // in any specific order.
133 //
134 // The definition of parameters is by simply creating an Input and then
135 // using the appropriate Input Create member function. Then the
136 // programmer adds to the list of parameters as necessary.
137 // </synopsis>
138 //
139 // <example>
140 // <srcblock>
141 // 01 #include <casacore/casa/Inputs/Input.h> // need this if you want it to work
142 // 02 #include <aips/Plot.h>
143 // 03 int main(int argc, const char* argv[])
144 // 04 {
145 // 05 Input inputs(1);
146 // 06 // Define our input structure
147 // 07 inputs.version("Id: xyPlot.C,v 1.1 1993/01/29 20:45:48 bglenden Exp");
148 // 08 inputs.create("xyfile",
149 // 09 "/tmp/xy.aipsio",
150 // 10 "File which contains xy vectors",
151 // 11 "InFile");
152 // 12 inputs.create("overplot", "False", "Multiple plots?", "Bool");
153 // 13 inputs.create("lines", "True", "Plot lines or points?", "Bool");
154 // 14
155 // 15 // and Fill them from the command line
156 // 16 inputs.readArguments(argc, argv);
157 // 17
158 // 18 try {
159 // 19 const Char *filename = inputs.getString("xyfile");
160 // 20 AipsIO xyfile(filename, ByteIO::Old);
161 // 21 Vector<float> x, y;
162 // 22 Plot plot;
163 // 23
164 // 24 xyfile >> x >> y; // initial vectors
165 // 25 plot(x,y,inputs.getBool("lines"));
166 // 26
167 // 27 for (;;) { // forever
168 // 28 xyfile >> x >> y;
169 // 29 if (inputs.getBool("overplot") == True) {
170 // 30 plot(x,y,inputs.getBool("lines"));
171 // 31 } else {
172 // 32 plot.newPlot();
173 // 33 plot(x,y,inputs.getBool("lines"));
174 // 34 }
175 // 35 }
176 // 36 } catch (AipsIOError x) {
177 // 37 ; // nothing - no more data
178 // 38 } catch (AllocError x) {
179 // 39 cerr << "AllocError : " << x.what() << endl;
180 // 40 cerr << "Size is : " << x.size() << endl;
181 // 41 } catch (std::exception x) {
182 // 42 cerr << "aipserror: error " << x.what() << endl;
183 // 43 return 1;
184 // 44 }
185 // 45
186 // 46 cout << "Any key to exit:\n";
187 // 47
188 // 48 char ch;
189 // 49 cin.get(ch);
190 // 50
191 // 51 return 0;
192 // 52 }
193 // </srcblock>
194 // Let us discuss this program line for line.
195 //
196 // 03 - This is the method of passing the command line through to the
197 // main body of code. This obviously makes it mandatory. The inclusion
198 // of the argc, argv is very well discussed in Stroustrup, The
199 // C++ Programming Language, page 87.
200 //
201 // 05 - The instantiation of Input in the variable inputs(1) is done with
202 // an integer argument of (1) to indicate the constructor should build
203 // inputs with a pair of system parameters and read in values for them.
204 // An argument of (0) would build an Input that was empty and would
205 // obligate the programmer to build a list of Params explicitly.
206 //
207 // 07 - The version of the code is stored within the Input. Note the
208 // optional use of RCS keyword substitution. See the "co" man page for
209 // details. This allows the code to be automatically updated.
210 //
211 // 08-11 - The create member function of Input builds, in this case, a
212 // parameter called xyfile, immediately filled with the String containing
213 // the directory that holds the data. The help String is useful for new
214 // users or prompting. The fourth argument of InFile is the optional
215 // type of the parameter's value. Any suitable String may be used.
216 // Missing from this example are the optional fifth and sixth arguments,
217 // the parameter's value's range and units, respectively.
218 //
219 // 12 - This is another instantiation of a Param inside of Input. This
220 // parameter will be referenced by the keyword "overplot". It is
221 // initialized to False and is of type Bool.
222 //
223 // 13 - This line is the third and final Param placed in inputs and is
224 // recognized by the code when accessed with keyword "lines".
225 //
226 // 16 - The call of readArguments(argc, argv) should be done after the
227 // list of Params has been completed. This line of code fills the values
228 // from the command line. A keyword that doesn't match will throw an
229 // error.
230 //
231 // 19 - At this point the local variable filename is initialized to the
232 // String value held within the parameter accessed through the key
233 // "xyfile". Recall that the value of xyfile was originally set to
234 // "/tmp/xy.aipsio" but would be replaced with the proper value at
235 // execution. The getString member function returns either the default
236 // value specified during the xyfile parameter's instantiation or the
237 // value placed into it from the command line use of xyfile=myfile.
238 //
239 // 25 - Here the boolean value of the Param called lines is inserted into
240 // the call to the function plot.
241 //
242 // 29 - Again the Input interface has its parameter called overplot
243 // return a boolean to be used as a test for an "if". The getBool(key)
244 // Input member function may be reading the default value of the
245 // appropriate parameter called key or using the value passed from the
246 // command line.
247 //
248 // 30 & 33 - Another call to plot that uses the boolean value stored in
249 // the parameter called lines.
250 // </example>
251 //
252 //<motivation>
253 // This module fit the early needs of a a simple user interface.
254 // </motivation>
255 
256 // <todo asof="Thu 199504/06 21:26:43 GMT">
257 // <li> possibly replace the Param class with Keywords
258 // </todo>
259 
260 // </module>
261 
262 
263 } //# NAMESPACE CASACORE - END
264 
265 #endif
266 
267 
268 
269 
270 
271