casacore
Loading...
Searching...
No Matches
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
33#include <casacore/casa/Inputs/Input.h>
34#include <casacore/casa/Inputs/Param.h>
35
36namespace 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
this file contains all the compiler specific defines
Definition mainpage.dox:28