00001 //# Inputs.h: a module for simple command line user interface classes 00002 //# Copyright (C) 1994,1995,1996,1999,2000 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id$ 00027 00028 #ifndef CASA_INPUTS_H 00029 #define CASA_INPUTS_H 00030 00031 #include <casacore/casa/aips.h> 00032 00033 #include <casacore/casa/Inputs/Input.h> 00034 #include <casacore/casa/Inputs/Param.h> 00035 00036 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00037 00038 // <module> 00039 // 00040 // <summary> 00041 // A module for simple command line user interface classes 00042 // </summary> 00043 00044 // <prerequisite> 00045 // <li> String 00046 // <li> The C language int main(int argc, const char* argv[]) convention. 00047 // </prerequisite> 00048 00049 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" demos=""> 00050 //</reviewed> 00051 00052 // <etymology> 00053 // The Inputs module name reflects the Casacore convention of pluralizing 00054 // the name of the major class it contains. 00055 // The Input class name is a reflection of it's role as the early command 00056 // line user interface for Casacore applications. This class provides "inputs" 00057 // in the form "key=value" or "-key value." 00058 //</etymology> 00059 // 00060 // <synopsis> 00061 00062 // During the old AIPS++ prototyping stage a basic command line user 00063 // interface was developed. This attempt at easing the trouble of passing 00064 // information to an executable program resulted in a set of C++ classes 00065 // called Param and Input. The programmer may simply include the Input 00066 // class into their code and have immediate Command Line User Interface 00067 // (CLUI) capabilities. The programmer's Casacore application is run from 00068 // the unix level prompt by invoking its name and listing linearly on the 00069 // same command line the "keyword=values" or "-keyword values" associated 00070 // with proper execution. The Input and Param classes will successfully 00071 // parse the command line into the executable program and check for 00072 // appropriateness. 00073 00074 // The CLUI capabilities are further extended to a Graphical User 00075 // Interface through the use of the Khoros Cantata environment. The user 00076 // starts up Cantata from the unix prompt and, by utilizing a series of 00077 // pull down windows, invisibly creates an X-based window for visual 00078 // display of all parameters associated with the Casacore application's 00079 // need for external input. 00080 00081 // The basic command line user interface is an ordered series of 00082 // "keyword=value" pairs, which we call parameters. The names parameter 00083 // and keyword may correctly be used to refer to each other. 00084 // 00085 // The class Param (see Param.h) implements one single such parameter. 00086 // Values may be Int, Block<Int>, double, Block<double>, Bool, or 00087 // Strings. In addition to a name and a value, a Param parameter has a 00088 // variety of other attributes, such as a one-line help string (useful 00089 // when being prompted for input or with hypertext identifiers, etc...), 00090 // a type, a range and optional units. All of these attributes are 00091 // character strings; parsing and error checking is done at a different 00092 // (hidden) level. The programmer, however, will never interact with a 00093 // parameter through it's Param class interface. Interaction is done 00094 // with the class Input, which is a container of Param's, with a variety 00095 // of user interface attributes (help-level, debug-level, etc...). 00096 // 00097 // Although the programmer must supply the user interface with a number 00098 // of predefined program parameters, the user interface itself will 00099 // create a small number of system parameters (help=, debug=). The 00100 // purpose of these is to tell the task how to communicate with the user 00101 // and it's environment, and give the user control over these items. For 00102 // example, the user may want to see (debug) messages above a certain 00103 // threshold level. The programmer simply adds debug levels to their 00104 // code and allows the user to specify how deeply they wish the debugging 00105 // to progress. 00106 // 00107 // For example, a interactive UNIX shell session may look like: 00108 // 00109 //<srcblock> 00110 // 1% MyProgram key1=val1 key3=val3 00111 // 2% MyProgram key1=val1 key2=val3 debug=5 00112 // 3% MyProgram help=prompt 00113 // 4% MyProgram help=pane > prog.pane 00114 //</srcblock> 00115 // 00116 // In command 1% the user has set several parameters for the program 00117 // MyProgram to applicable values. The 2% command line invokes the 00118 // executable and sets the level of displayed debugging to the programmer 00119 // specified 5th level. Command 3%: the user is prompted, and parameter 00120 // default values are restored. Command 4% gives an example of the 00121 // self-describing mode of programs, where a pane description file for 00122 // Khoros has been constructed. The latter is the first step toward 00123 // building a Khoros Graphic User Interface. 00124 // 00125 // The Input class is a means for building a linked list of parameters 00126 // and gaining access to them once created. Input takes care of 00127 // system/environment variables and assigns their values within the 00128 // programmer's code. The linked list of parameters is limited only by 00129 // the number of names the programmer can dream up. The programmer need 00130 // not think hard on the order of definition of parameters in Input. The 00131 // list of key=values given on the command line by the user need not be 00132 // in any specific order. 00133 // 00134 // The definition of parameters is by simply creating an Input and then 00135 // using the appropriate Input Create member function. Then the 00136 // programmer adds to the list of parameters as necessary. 00137 // </synopsis> 00138 // 00139 // <example> 00140 // <srcblock> 00141 // 01 #include <casacore/casa/Inputs/Input.h> // need this if you want it to work 00142 // 02 #include <aips/Plot.h> 00143 // 03 int main(int argc, const char* argv[]) 00144 // 04 { 00145 // 05 Input inputs(1); 00146 // 06 // Define our input structure 00147 // 07 inputs.version("Id: xyPlot.C,v 1.1 1993/01/29 20:45:48 bglenden Exp"); 00148 // 08 inputs.create("xyfile", 00149 // 09 "/tmp/xy.aipsio", 00150 // 10 "File which contains xy vectors", 00151 // 11 "InFile"); 00152 // 12 inputs.create("overplot", "False", "Multiple plots?", "Bool"); 00153 // 13 inputs.create("lines", "True", "Plot lines or points?", "Bool"); 00154 // 14 00155 // 15 // and Fill them from the command line 00156 // 16 inputs.readArguments(argc, argv); 00157 // 17 00158 // 18 try { 00159 // 19 const Char *filename = inputs.getString("xyfile"); 00160 // 20 AipsIO xyfile(filename, ByteIO::Old); 00161 // 21 Vector<float> x, y; 00162 // 22 Plot plot; 00163 // 23 00164 // 24 xyfile >> x >> y; // initial vectors 00165 // 25 plot(x,y,inputs.getBool("lines")); 00166 // 26 00167 // 27 for (;;) { // forever 00168 // 28 xyfile >> x >> y; 00169 // 29 if (inputs.getBool("overplot") == True) { 00170 // 30 plot(x,y,inputs.getBool("lines")); 00171 // 31 } else { 00172 // 32 plot.newPlot(); 00173 // 33 plot(x,y,inputs.getBool("lines")); 00174 // 34 } 00175 // 35 } 00176 // 36 } catch (AipsIOError x) { 00177 // 37 ; // nothing - no more data 00178 // 38 } catch (AllocError x) { 00179 // 39 cerr << "AllocError : " << x.getMesg() << endl; 00180 // 40 cerr << "Size is : " << x.size() << endl; 00181 // 41 } catch (AipsError x) { 00182 // 42 cerr << "aipserror: error " << x.getMesg() << endl; 00183 // 43 return 1; 00184 // 44 } 00185 // 45 00186 // 46 cout << "Any key to exit:\n"; 00187 // 47 00188 // 48 char ch; 00189 // 49 cin.get(ch); 00190 // 50 00191 // 51 return 0; 00192 // 52 } 00193 // </srcblock> 00194 // Let us discuss this program line for line. 00195 // 00196 // 03 - This is the method of passing the command line through to the 00197 // main body of code. This obviously makes it mandatory. The inclusion 00198 // of the argc, argv is very well discussed in Stroustrup, The 00199 // C++ Programming Language, page 87. 00200 // 00201 // 05 - The instantiation of Input in the variable inputs(1) is done with 00202 // an integer argument of (1) to indicate the constructor should build 00203 // inputs with a pair of system parameters and read in values for them. 00204 // An argument of (0) would build an Input that was empty and would 00205 // obligate the programmer to build a list of Params explicitly. 00206 // 00207 // 07 - The version of the code is stored within the Input. Note the 00208 // optional use of RCS keyword substitution. See the "co" man page for 00209 // details. This allows the code to be automatically updated. 00210 // 00211 // 08-11 - The create member function of Input builds, in this case, a 00212 // parameter called xyfile, immediately filled with the String containing 00213 // the directory that holds the data. The help String is useful for new 00214 // users or prompting. The fourth argument of InFile is the optional 00215 // type of the parameter's value. Any suitable String may be used. 00216 // Missing from this example are the optional fifth and sixth arguments, 00217 // the parameter's value's range and units, respectively. 00218 // 00219 // 12 - This is another instantiation of a Param inside of Input. This 00220 // parameter will be referenced by the keyword "overplot". It is 00221 // initialized to False and is of type Bool. 00222 // 00223 // 13 - This line is the third and final Param placed in inputs and is 00224 // recognized by the code when accessed with keyword "lines". 00225 // 00226 // 16 - The call of readArguments(argc, argv) should be done after the 00227 // list of Params has been completed. This line of code fills the values 00228 // from the command line. A keyword that doesn't match will throw an 00229 // error. 00230 // 00231 // 19 - At this point the local variable filename is initialized to the 00232 // String value held within the parameter accessed through the key 00233 // "xyfile". Recall that the value of xyfile was originally set to 00234 // "/tmp/xy.aipsio" but would be replaced with the proper value at 00235 // execution. The getString member function returns either the default 00236 // value specified during the xyfile parameter's instantiation or the 00237 // value placed into it from the command line use of xyfile=myfile. 00238 // 00239 // 25 - Here the boolean value of the Param called lines is inserted into 00240 // the call to the function plot. 00241 // 00242 // 29 - Again the Input interface has its parameter called overplot 00243 // return a boolean to be used as a test for an "if". The getBool(key) 00244 // Input member function may be reading the default value of the 00245 // appropriate parameter called key or using the value passed from the 00246 // command line. 00247 // 00248 // 30 & 33 - Another call to plot that uses the boolean value stored in 00249 // the parameter called lines. 00250 // </example> 00251 // 00252 //<motivation> 00253 // This module fit the early needs of a a simple user interface. 00254 // </motivation> 00255 00256 // <todo asof="Thu 199504/06 21:26:43 GMT"> 00257 // <li> possibly replace the Param class with Keywords 00258 // </todo> 00259 00260 // </module> 00261 00262 00263 } //# NAMESPACE CASACORE - END 00264 00265 #endif 00266 00267 00268 00269 00270 00271